Intro to gwrefpy#

gwrefpy is a Python package for detecting deviations in groundwater time series.

This notebook can be downloaded from the source code here.

Problem Statement

The problem: Groundwater levels rise and fall naturally with weather and the seasons. So when an observation well behaves unexpectedly, how do we tell whether human activity (pumping, construction, drainage) is to blame, or whether it is just natural variation?

How gwrefpy solves it: An observation well (the one we care about) is compared against one or more reference wells that represent undisturbed, natural conditions. gwrefpy fits the observation well to the reference wells by regression; once later measurements stop following that fit, a deviation — some kind of influence — has occurred.

The two building blocks of gwrefpy are Model — a site or area of interest — and Well — a location where groundwater data is collected. A Model holds any number of Well objects, and the two can be created independently and linked together later.

Let’s start by importing gwrefpy (along with pandas, which we use to load the data).

import pandas as pd

import gwrefpy as gr

Creating a Model#

A Model represents a site or area of interest and is made up of any number of wells. Here we create one named "My First gwrefpy Model".

model = gr.Model(name="My First gwrefpy Model")

Creating Wells#

A Well is a location where groundwater data is collected. Each well is either an observation well or a reference well.

Reference wells#

Wells that are used to represent natural conditions.

Observation wells#

Wells that the user is interested in to see if they are influenced by anthropogenic activities.

We will create two observation wells and two reference wells and later add them to our model.

Creating data timeseries#

A well’s data is a pandas time series. In this example we build those series from CSV files.

Tip

Data types can be other than CSV. Check the pandas documentation for inspiration.

base_url = "https://github.com/sgfsweden/gwrefpy/raw/dev/docs/user_guide/data"


def load_series(filename):
    df = pd.read_csv(
        f"{base_url}/{filename}",
        sep=";",
        index_col=0,
        parse_dates=True,
    )
    # Each CSV has a single value column; take it as a pandas Series.
    return df.iloc[:, 0]


obs1_series = load_series("obs1_mod_wel.csv")
ref1_series = load_series("ref1_mod_wel.csv")
obs2_series = load_series("obs2_mod_wel.csv")
ref2_series = load_series("ref2_mod_wel.csv")

Next we create the Well objects and attach the time series to them.

The Well object

Well takes three arguments: a name (string), is_reference (a boolean choosing reference or observation well), and the timeseries (the pandas series we created earlier).

obs1 = gr.Well(name="obs1", is_reference=False, timeseries=obs1_series)
ref1 = gr.Well(name="ref1", is_reference=True, timeseries=ref1_series)
obs2 = gr.Well(name="obs2", is_reference=False, timeseries=obs2_series)
ref2 = gr.Well(name="ref2", is_reference=True, timeseries=ref2_series)

Now we add the wells to the model.

Add wells to the model#

We add wells with add_well(), passing either a single well or a list of wells.

# Add several wells at once with a list
model.add_well([obs1, ref1, obs2])

# Add a single well
model.add_well(ref2)

Now let’s confirm the wells are stored in the model.

Check which wells are included in the model#

The obs_wells and ref_wells properties list the observation and reference wells in the model.

model.obs_wells
[Well(name=obs1), Well(name=obs2)]

Check the reference wells:

model.ref_wells
[Well(name=ref1), Well(name=ref2)]

We can look up specific wells by name with get_wells(), passing one name or a list of names.

model.get_wells("obs1")
model.get_wells(["obs1", "ref1"])
[Well(name=obs1), Well(name=ref1)]

The well_names property returns just the names of the wells in the model.

model.well_names
['obs1', 'ref1', 'obs2', 'ref2']

The model now holds two observation wells and two reference wells, ready for further analysis.

For an overview, wells_summary() returns a pandas DataFrame summarising every well.

model.wells_summary()
name well_type data_points start_date end_date mean_level latest_value latest_date latitude longitude elevation best_fit_ref_well best_rmse num_fits avg_rmse
0 obs1 observation 2078 2020-01-01 2025-09-08 15.467492 14.877000 2025-09-08 None None None None None NaN NaN
1 obs2 observation 2078 2020-01-01 2025-09-08 14.977455 14.832391 2025-09-08 None None None None None NaN NaN
2 ref1 reference 2078 2020-01-01 2025-09-08 25.799352 24.795000 2025-09-08 None None None NaN NaN 0.0 None
3 ref2 reference 2079 2020-01-01 2025-09-08 25.666046 25.900000 NaT None None None NaN NaN 0.0 None

Delete wells from the model#

We remove wells with delete_well(), passing a Well object (or a list of them).

model.delete_well([ref1])

# Confirm it was removed
model.well_names
['obs1', 'obs2', 'ref2']

That’s it for the intro to gwrefpy.

The next notebooks build on this model to cover the rest of gwrefpy: pairing observation and reference wells, fitting them, and plotting the results.