diff --git a/dawacotools/analysis.py b/dawacotools/analysis.py index 5df49fc..8d66a55 100644 --- a/dawacotools/analysis.py +++ b/dawacotools/analysis.py @@ -46,44 +46,82 @@ def compute_residence_time( ): """Compute the residence time of the water extracted from a plug-flow reservoir. - The residence time is computed from the historic flows through a reservoir of a given volume. Either - provide the pore_volume_reservoir or the average_residence_time parameters. + The residence time is computed from historic flow rates through a reservoir of a given volume. The + cumulative transported volume is derived from elapsed days in ``flow.index``; therefore ``flow`` values + must be volumetric rates per day (for example m³/day). Convert rates in other time units before calling + this function, e.g. multiply m³/hour by 24. IKIEF 9100: >> pore_volume_reservoir = 2 * lengte_strang * afstand_pand_put / porositeit >> 128571 m3 = 2 * 500 * 45 / 0.35 - Given a certain volume of the reservoir, the residence time - Parameters ---------- flow : pandas.Series - The flow in the reservoir in m3/h. + Volumetric flow rate through the reservoir in m³/day. The index must be a strictly increasing + pandas.DatetimeIndex; flow is linearly interpolated between timestamps and integrated over elapsed days. pore_volume_reservoir : float, optional - The pore volume of the reservoir in m3. If not given, it is computed as the product of the porosity and the volume of the reservoir. + The pore volume of the reservoir in the same volume unit as ``flow``. Provide either this value or + ``average_residence_time``. average_residence_time : float, optional - The average residence time in days. If no pore_volume_reservoir is given, the pore volume is computed as the product of the average residence time and the mean flow. + The average residence time in days. If no ``pore_volume_reservoir`` is given, the pore volume is computed + as the product of the average residence time and the time-weighted mean flow. extraction_infiltration : str, optional - The type of flow. Either 'extraction' or 'infiltration'. Extraction refers to backward modeling: how many days ago did this extracted water infiltrate. Infiltration refers to forward modeling: how many days will it take for this infiltrated water to be extracted. + The type of flow. Either 'extraction' or 'infiltration'. Extraction refers to backward modeling: how many + days ago did this extracted water infiltrate. Infiltration refers to forward modeling: how many days will it + take for this infiltrated water to be extracted. Default is 'extraction'. + retardation_factor : float, optional + Multiplicative factor for solute retardation relative to water movement. Default is 1. Returns ------- pandas.Series The residence time in days. """ - if pore_volume_reservoir is None and average_residence_time is not None: - pore_volume_reservoir = average_residence_time * flow.mean() + if pore_volume_reservoir is None and average_residence_time is None: + msg = "Provide either pore_volume_reservoir or average_residence_time" + raise ValueError(msg) + + if not isinstance(flow.index, pd.DatetimeIndex): + msg = "flow must be indexed by a pandas.DatetimeIndex" + raise TypeError(msg) - cum_flow_val = integrate.cumulative_simpson(y=flow.values, dx=1, initial=0.0) # m3 - interp_cum_flow_nu = interpolate.interp1d(cum_flow_val, flow.index, fill_value="extrapolate") + minimum_timestamps = 2 + if len(flow.index) < minimum_timestamps: + msg = "flow must contain at least two timestamps" + raise ValueError(msg) + + elapsed_days = ((flow.index - flow.index[0]) / pd.to_timedelta(1, unit="D")).to_numpy(dtype=float) + if not np.all(np.diff(elapsed_days) > 0.0): + msg = "flow.index must be strictly increasing" + raise ValueError(msg) + + flow_values = flow.to_numpy(dtype=float) + cum_flow_val = integrate.cumulative_trapezoid(y=flow_values, x=elapsed_days, initial=0.0) + + if not np.all(np.diff(cum_flow_val) > 0.0): + msg = "Cumulative flow must be strictly increasing; use positive flow rates through the reservoir" + raise ValueError(msg) + + if pore_volume_reservoir is None and average_residence_time is not None: + mean_flow = cum_flow_val[-1] / elapsed_days[-1] + pore_volume_reservoir = average_residence_time * mean_flow + + transport_volume = pore_volume_reservoir * retardation_factor + elapsed_at_cumulative_flow = interpolate.interp1d( + cum_flow_val, + elapsed_days, + fill_value="extrapolate", + assume_sorted=True, + ) if extraction_infiltration == "extraction": - toen = pd.to_datetime(interp_cum_flow_nu(cum_flow_val - pore_volume_reservoir * retardation_factor)) - residence_time = (flow.index - toen) / pd.to_timedelta(1, unit="D") + infiltration_time = elapsed_at_cumulative_flow(cum_flow_val - transport_volume) + residence_time = elapsed_days - infiltration_time elif extraction_infiltration == "infiltration": - dan = pd.to_datetime(interp_cum_flow_nu(cum_flow_val + pore_volume_reservoir * retardation_factor)) - residence_time = (dan - flow.index) / pd.to_timedelta(1, unit="D") + extraction_time = elapsed_at_cumulative_flow(cum_flow_val + transport_volume) + residence_time = extraction_time - elapsed_days else: msg = "extraction_infiltration should be 'extraction' or 'infiltration'" raise ValueError(msg) @@ -200,8 +238,6 @@ def get_well_info(mpcode=None, filternr=None): """Filter and MP data""" out["filter_metadata"] = get_daw_filters( mpcode=mpcode, - mv=True, - betrouwbaarheid=False, filternr=filternr, partial_match_mpcode=True, ) @@ -209,9 +245,10 @@ def get_well_info(mpcode=None, filternr=None): msg = "Better specify mpcode and filter number" raise ValueError(msg) - mpcode = out["filter_metadata"].iloc[0].FiltMpCode - filternr = out["filter_metadata"].iloc[0].Filtnr - x, y = out["filter_metadata"].iloc[0].Xcoor, out["filter_metadata"].iloc[0].Ycoor + filter_metadata = out["filter_metadata"].iloc[0] + mpcode = filter_metadata["MpCode"] + filternr = filter_metadata["Filtnr"] + x, y = filter_metadata["Xcoor"], filter_metadata["Ycoor"] """Groundwater levels""" out["gws"] = get_daw_ts_stijghgt(mpcode=mpcode, filternr=filternr) diff --git a/tests/mock_dawaco.py b/tests/mock_dawaco.py index 9f7434f..81b3fde 100644 --- a/tests/mock_dawaco.py +++ b/tests/mock_dawaco.py @@ -123,6 +123,8 @@ def _write_groundwater_levels(connection: Connection) -> None: {"filtrec": 101, "datum": "2020-01-06", "tijd": "00:00", "meting_nap": 1.40, "Temp": 9.0}, {"filtrec": 102, "datum": "2020-01-01", "tijd": "00:00", "meting_nap": 0.50, "Temp": 7.5}, {"filtrec": 103, "datum": "2020-01-01", "tijd": "00:00", "meting_nap": 0.75, "Temp": 7.0}, + {"filtrec": 103, "datum": "2020-01-03", "tijd": "00:00", "meting_nap": 0.95, "Temp": 7.2}, + {"filtrec": 103, "datum": "2020-01-06", "tijd": "00:00", "meting_nap": 1.35, "Temp": 7.4}, ]).to_sql("Stijghgt", connection, index=False, if_exists="replace") diff --git a/tests/test_analysis.py b/tests/test_analysis.py index 13c4b1c..255a14d 100644 --- a/tests/test_analysis.py +++ b/tests/test_analysis.py @@ -13,6 +13,43 @@ def test_remove_outliers_replaces_values_outside_threshold(): assert result.iloc[:3].notna().all() +def test_compute_residence_time_uses_datetime_elapsed_days_for_explicit_pore_volume(): + index = pd.date_range("2020-01-01", periods=5, freq="12h") + flow = pd.Series(12.0, index=index) + + result = dt.analysis.compute_residence_time(flow, pore_volume_reservoir=6.0) + + expected = pd.Series(0.5, index=index) + pd.testing.assert_series_equal(result, expected) + + +def test_compute_residence_time_can_derive_pore_volume_from_average_residence_time(): + index = pd.date_range("2020-01-01", periods=5, freq="D") + flow = pd.Series(8.0, index=index) + + result = dt.analysis.compute_residence_time(flow, average_residence_time=1.25) + + expected = pd.Series(1.25, index=index) + pd.testing.assert_series_equal(result, expected) + + +def test_compute_residence_time_supports_flow_direction_and_retardation(): + index = pd.date_range("2020-01-01", periods=5, freq="D") + flow = pd.Series(10.0, index=index) + + extraction = dt.analysis.compute_residence_time(flow, pore_volume_reservoir=20.0) + infiltration = dt.analysis.compute_residence_time( + flow, + pore_volume_reservoir=20.0, + extraction_infiltration="infiltration", + ) + retarded = dt.analysis.compute_residence_time(flow, pore_volume_reservoir=20.0, retardation_factor=1.5) + + pd.testing.assert_series_equal(extraction, pd.Series(2.0, index=index)) + pd.testing.assert_series_equal(infiltration, pd.Series(2.0, index=index)) + pd.testing.assert_series_equal(retarded, pd.Series(3.0, index=index)) + + def test_potential_to_flow_uses_filter_metadata_and_static_heads(): result = dt.potential_to_flow( mpcode1="MOCK001", @@ -32,6 +69,63 @@ def test_potential_to_flow_uses_filter_metadata_and_static_heads(): pd.testing.assert_series_equal(result["duration"], pd.Series([1.25]), check_names=False) +def test_potential_to_flow_resamples_dynamic_head_series(): + result = dt.potential_to_flow( + mpcode1="MOCK001", + filternr1=1, + mpcode2="MOCK002", + filternr2=1, + hydraulic_conductivity=10.0, + porosity=0.25, + ) + + index = pd.date_range("2020-01-01", "2020-01-06", freq="D") + expected_gradient = pd.Series([0.05, 0.05, np.nan, np.nan, np.nan, 0.01], index=index) + expected_duration = pd.Series([2.5, 2.5, np.nan, np.nan, np.nan, 12.5], index=index) + + pd.testing.assert_series_equal(result["gradient"], expected_gradient, check_freq=False, check_names=False) + pd.testing.assert_series_equal(result["duration"], expected_duration, check_freq=False, check_names=False) + + +def test_get_well_info_uses_mock_database_and_current_filter_columns(monkeypatch): + meteo_calls = [] + regis_calls = [] + + def fake_meteo_from_loc(*, x, y, mettype, start_date, end_date): + meteo_calls.append({ + "x": x, + "y": y, + "mettype": mettype, + "start_date": start_date, + "end_date": end_date, + }) + return pd.Series([1.0], index=pd.DatetimeIndex([start_date]), name=mettype), [("MOCK", 0.0, None)] + + regis = {"source": "synthetic-regis"} + + def fake_regis_ds(x, y, keys=None): + regis_calls.append((x, y, keys)) + return regis + + monkeypatch.setattr(dt.analysis, "get_daw_meteo_from_loc", fake_meteo_from_loc) + monkeypatch.setattr(dt.analysis, "get_regis_ds", fake_regis_ds) + + info = dt.get_well_info(mpcode="MOCK001", filternr=1) + + assert info["filter_metadata"].iloc[0]["MpCode"] == "MOCK001" + assert info["filter_metadata"].iloc[0]["Filtnr"] == 1 + assert info["gws"].loc["2020-01-01"] == 1.0 + assert info["gwt"].loc["2020-01-01"] == 8.0 + assert list(info["boring"].index.unique()) == ["MOCK001"] + assert list(info["triwaco"]["Mpcode"].unique()) == ["MOCK001"] + assert info["regis"] is regis + assert regis_calls == [(100000.0, 500000.0, None)] + assert {call["mettype"] for call in meteo_calls} == set(dt.analysis.meteo_pars) + assert all(call["x"] == 100000.0 and call["y"] == 500000.0 for call in meteo_calls) + assert all(call["start_date"] == pd.Timestamp("2020-01-01") for call in meteo_calls) + assert all(call["end_date"] == pd.Timestamp("2020-01-06") for call in meteo_calls) + + def test_get_cluster_mps_finds_nearby_monitoring_points(): mps = dt.get_daw_mps()