Model#

A class representing a groundwater model that can contain multiple wells.

class src.gwrefpy.model.Model(name: str)[source]#

Bases: FitBase, Plotter

A class representing a groundwater model that can contain multiple wells.

Parameters:: name (str) – The name of the model. If the name ends with “.gwref”, it is treated as a filename and the model is loaded from that file.

add_well(well: Well | list[Well])[source]#

Add a well or a list of wells to the model.

Parameters:: well (Well or list of Wells) – The well or list of wells to add to the model.
Returns:: This method modifies the model in place.
Return type:: None

best_fit(obs_well: str | Well, ref_wells: list[str | Well] | None = None, method: Literal['linearregression'] = 'linearregression', **kwargs) → FitResultData#

Find the best fit for the model using the provided wells.

Parameters:

obs_well (Well or list of Well or None, optional) – The observation well to use for fitting.
ref_wells (Well or list of Well or None, optional) – The reference wells to test. If None, all reference wells in the model will be used (default is None).
method (Literal["linearregression"]) – Method with which to perform regression. Currently only supports linear regression.
**kwargs – Keyword arguments to pass to the fitting method. For example, you can use offset, p, tmin, tmax, and aggregation to control the fitting

Returns:

Returns the best fit for the given observation well.

Return type:

FitResultData

delete_well(well: Well | list[Well])[source]#

Delete a well or a list of wells from the model.

Parameters:: well (Well or list of Wells) – The well or list of wells to add to the model.
Returns:: This method modifies the model in place.
Return type:: None

Fit reference well(s) to observation well(s) using regression.

Parameters:

obs_well (Well | list[Well] | str | list[str]) – The observation well(s) to use for fitting. Can be Well objects, well names (strings), or lists of either. If a list is provided, each well will be paired with the corresponding reference well by index.
ref_well (Well | list[Well] | str | list[str]) – The reference well(s) to use for fitting. Can be Well objects, well names (strings), or lists of either. If a list is provided, each well will be paired with the corresponding observation well by index.
offset (pd.DateOffset | pd.Timedelta | str) – The offset to apply to the time series when grouping within time equivalents.
aggregation (Literal["mean", "median", "min", "max"], optional) – The aggregation method to use when grouping data points within time equivalents (default is “mean”).
p (float, optional) – The confidence level for the fit (default is 0.95).
method (Literal["linearregression"]) – Method with which to perform regression. Currently only supports linear regression.
tmin (pd.Timestamp | str | None = None) – Minimum time for calibration period.
tmax (pd.Timestamp | str | None = None) – Maximum time for calibration period.
report (bool, optional) – Whether to print fit results summary (default is True).

Returns:

If single wells are provided, returns a single FitResultData object. If lists of wells are provided, returns a list of FitResultData objects for each obs_well/ref_well pair.

Return type:

FitResultData | list[FitResultData]

Raises:

ValueError – If lists are provided but have different lengths.

fits_summary() → DataFrame[source]#

Get a summary DataFrame of all fit results in the model.

Returns:: DataFrame with common columns (ref_well_name, obs_well_name, method, rmse, etc.) and method-specific columns with appropriate prefixes (e.g., linreg_slope, linreg_intercept)
Return type:: pd.DataFrame

get_fits(well: Well | str) → list[FitResultData] | FitResultData | None#

Get all fit results involving a specific well.

Parameters:: well (Well | str) – The well to check.
Returns:: A list of fit results involving the specified well.
Return type:: list[FitResultData] | FitResultData | None

get_wells(names: list[str] | str) → Well | list[Well][source]#

Get wells from the model by their names.

Parameters:: names (list of str or str) – The name or list of names of the wells to retrieve.
Returns:: The well or list of wells with the specified names.
Return type:: Well | list[Well]
Raises:: ValueError – If any of the specified well names are not found in the model.

property obs_wells: list[Well]#: List of observation wells in the model.

obs_wells_summary() → DataFrame[source]#

Get a summary DataFrame of observation wells in the model.

Returns:: DataFrame with columns: name, data_points, start_date, end_date, mean_level, latest_value, latest_date, latitude, longitude, elevation, best_fit_ref_well, best_rmse
Return type:: pd.DataFrame

open_project(filepath)[source]#

Load the model from a file.

Parameters:: filepath (str) – The path to the file from which the model will be loaded.
Returns:: This method loads the model from a file.
Return type:: None

plot_fitmethod(fits: FitResultData | list[FitResultData] = None, title: str = 'Fit Method Plot', xlabel: str = 'Hydraulic Head Reference Well', ylabel: str = 'Hydraulic Head Observation Well', plot_style: str | None = None, color_style: str | None = None, save_path: str | None = None, plot_separately: bool = False, plot_fit_period: bool = True, ax: Axes | None = None, **kwargs) → tuple[Figure | SubFigure, Axes] | tuple[list[Figure], list[Axes]]#

This method plots the time series data for all fits in the model.

Parameters:

fits (FitResultData | list[FitResultData]) – A FitResultData instance or a list of FitResultData instances containing the fit results to be plotted. If None, all fits will be plotted.
title (str) – The title of the plot.
xlabel (str) – The label for the x-axis.
ylabel (str) – The label for the y-axis.
plot_style (str | None) – The style of the plot. Options are “fancy”, “scientific”, or None. If None, uses matplotlib defaults without custom styling.
color_style (str | None) – The color style of the plot. Options are “color”, “monochrome”, or None. If None, uses matplotlib defaults without custom colors.
save_path (str | None) – If provided, the plot will be saved to this path. If the plot_separately parameter is True, the fit’s observation well name will be appended to the file name.
plot_separately (bool) – If True, each fit will be plotted in a separate figure. Default is False.
plot_fit_period (bool) – If True, the data points within the fit period will be highlighted. Default is True.
ax (matplotlib.axes.Axes | None) – Optional matplotlib Axes object to plot on. If provided, the plot will be drawn on this axes instead of creating a new figure. Not compatible with plot_separately=True.
**kwargs (dict) –
Additional keyword arguments for customization. See the documentation of Matplotlib’s plt.subplots and plt.savefig for more details. Common kwargs include:
- figsize (tuple): Size of the figure (width, height) in inches.
- dpi (int): Dots per inch for the saved figure.

Returns:

fig (matplotlib.figure.Figure) – The figure object containing the plot.
ax (matplotlib.axes.Axes) – The axes object of the plot.

plot_fits(fits: FitResultData | list[FitResultData] | None = None, title: str = '', xlabel: str = 'Time', ylabel: str = 'Measurements', mark_outliers: bool = True, show_initiation_period: bool = False, plot_ref_well: bool = False, plot_style: str | None = None, color_style: str | None = None, save_path: str | None = None, num: int = 6, plot_separately: bool = False, ax: Axes | None = None, offset_text: dict[str, float] | None = None, **kwargs) → tuple[Figure | SubFigure, Axes] | tuple[list[Figure], list[Axes]]#

This method plots the time series data for all fits in the model.

Parameters:

fits (FitResultData | list[FitResultData] | None) – A FitResultData instance or a list of FitResultData instances containing the fit results to be plotted. If None, all fits will be plotted.
title (str) – The title of the plot.
xlabel (str) – The label for the x-axis.
ylabel (str) – The label for the y-axis.
mark_outliers (bool) – If True, outliers will be marked on the plot.
show_initiation_period (bool) – If True, the initiation period will be shaded on the plot. Default is False.
plot_ref_well (bool) – If True, the reference well data will be plotted. Default is False.
plot_style (str | None) – The style of the plot. Options are “fancy”, “scientific”, or None. If None, uses matplotlib defaults without custom styling.
color_style (str | None) – The color style of the plot. Options are “color”, “monochrome”, or None. If None, uses matplotlib defaults without custom colors.
save_path (str | None) – If provided, the plot will be saved to this path. If the plot_separately parameter is True, the fit’s observation well name will be appended to the file name.
num (int) – Number of ticks on the x-axis (default is 6).
plot_separately (bool) – If True, each fit will be plotted in a separate figure. Default is False.
ax (matplotlib.axes.Axes | None) – Optional matplotlib Axes object to plot on. If provided, the plot will be drawn on this axes instead of creating a new figure. Not compatible with plot_separately=True.
offset_text (dict[str, float]) – A dictionary containing well names as keys and vertical offset values as values. This is used to offset the text labels for specific wells to avoid overlap. Default is None, which means no offset.
**kwargs (dict) –
Additional keyword arguments for customization. See the documentation of Matplotlib’s plt.subplots and plt.savefig for more details. Common kwargs include:
- figsize (tuple): Size of the figure (width, height) in inches.
- dpi (int): Dots per inch for the saved figure.

Returns:

fig (matplotlib.figure.Figure) – The figure object containing the plot.
ax (matplotlib.axes.Axes) – The axes object of the plot.

This method plots the time series data for all fits in the model.

Parameters:

wells (Well | list[Well]) – A Well instance or a list of Well instances containing the wells to be plotted. If None, all wells will be plotted.
title (str) – The title of the plot.
xlabel (str) – The label for the x-axis.
ylabel (str) – The label for the y-axis.
plot_style (str | None) – The style of the plot. Options are “fancy”, “scientific”, or None. If None, uses matplotlib defaults without custom styling.
color_style (str | None) – The color style of the plot. Options are “color”, “monochrome”, or None. If None, uses matplotlib defaults without custom colors.
save_path (str | None) – If provided, the plot will be saved to this path. If the plot_separately parameter is True, the well name will be appended to the file name.
num (int) – Number of ticks on the x-axis (default is 6).
plot_separately (bool) – If True, each well will be plotted in a separate figure. Default is False.
ax (matplotlib.axes.Axes | None) – Optional matplotlib Axes object to plot on. If provided, the plot will be drawn on this axes instead of creating a new figure. Not compatible with plot_separately=True.
offset_text (dict[str, float]) – A dictionary containing well names as keys and vertical offset values as values. This is used to offset the text labels for specific wells to avoid overlap. Default is None, which means no offset.
**kwargs (dict) –
Additional keyword arguments for customization. See the documentation of Matplotlib’s plt.subplots and plt.savefig for more details. Common kwargs include:
- figsize (tuple): Size of the figure (width, height) in inches.
- dpi (int): Dots per inch for the saved figure.

Returns:

fig (matplotlib.figure.Figure) – The figure object containing the plot.
ax (matplotlib.axes.Axes) – The axes object of the plot.

property ref_wells: list[Well]#: List of reference wells in the model.

ref_wells_summary() → DataFrame[source]#

Get a summary DataFrame of reference wells in the model.

Returns:: DataFrame with columns: name, data_points, start_date, end_date, mean_level, latest_value, latest_date, latitude, longitude, elevation, num_fits, avg_rmse
Return type:: pd.DataFrame

remove_fits_by_n(obs_well: Well | str, n: int) → None#

Remove fit results for a specific observation well. Keeps only the best n fits based on RMSE.

Parameters:

obs_well (Well | str) – The observation well to check.
n (int) – The n value of the fit results to remove.

Returns:

Removes fits from the model’s fit list.

Return type:

None

save_project(filename=None, overwrite=False)[source]#

Save the model to a file.

Parameters:

filename (str or None, optional) – The name of the file where the model will be saved. The path can be included.
overwrite (bool, optional) – Whether to overwrite the file if it already exists (default is False).

Returns:

This method saves the model to a file.

Return type:

None

static show_plots()#: Display all open matplotlib plots.

property well_names: list[str]#: List of all well names in the model.

wells_summary() → DataFrame[source]#

Get a combined summary DataFrame of all wells in the model.

Returns:: Combined DataFrame with both observation and reference wells, including all columns from both summary types
Return type:: pd.DataFrame

Model#

This Page