From f7d0bcb10c5f86e5c591b7aeb6ab0606100ffaab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Wed, 6 Sep 2023 11:29:27 +0200 Subject: [PATCH 01/10] improve documentation time series settings - add typed dictionary definitions - add Time Series Settings section in StressModel and TimeSeries docs - update rcParams with new typed dicts --- pastas/rcparams.py | 105 ++++++++-------- pastas/stressmodels.py | 247 ++++++++++++++++++++++++++++++++------ pastas/timeseries.py | 51 +++++++- pastas/typing/__init__.py | 2 + pastas/typing/types.py | 80 +++++++++++- 5 files changed, 388 insertions(+), 97 deletions(-) diff --git a/pastas/rcparams.py b/pastas/rcparams.py index 85a3115d0..68a8d57ae 100644 --- a/pastas/rcparams.py +++ b/pastas/rcparams.py @@ -1,54 +1,59 @@ +from .typing import OseriesSettingsDict, StressSettingsDict + rcParams = { "timeseries": { - "oseries": {"fill_nan": "drop", "sample_down": "drop"}, - "prec": { - "sample_up": "bfill", - "sample_down": "mean", - "fill_nan": 0.0, - "fill_before": "mean", - "fill_after": "mean", - }, - "evap": { - "sample_up": "bfill", - "sample_down": "mean", - "fill_before": "mean", - "fill_after": "mean", - "fill_nan": "interpolate", - }, - "well": { - "sample_up": "bfill", - "sample_down": "mean", - "fill_nan": 0.0, - "fill_before": 0.0, - "fill_after": 0.0, - }, - "waterlevel": { - "sample_up": "interpolate", - "sample_down": "mean", - "fill_before": "mean", - "fill_after": "mean", - "fill_nan": "interpolate", - }, - "level": { - "sample_up": "interpolate", - "sample_down": "mean", - "fill_before": "mean", - "fill_after": "mean", - "fill_nan": "interpolate", - }, - "flux": { - "sample_up": "bfill", - "sample_down": "mean", - "fill_before": "mean", - "fill_after": "mean", - "fill_nan": 0.0, - }, - "quantity": { - "sample_up": "divide", - "sample_down": "sum", - "fill_before": "mean", - "fill_after": "mean", - "fill_nan": 0.0, - }, + "oseries": OseriesSettingsDict( + fill_nan="drop", + sample_down="drop", + ), + "prec": StressSettingsDict( + sample_up="bfill", + sample_down="mean", + fill_nan=0.0, + fill_before="mean", + fill_after="mean", + ), + "evap": StressSettingsDict( + sample_up="bfill", + sample_down="mean", + fill_before="mean", + fill_after="mean", + fill_nan="interpolate", + ), + "well": StressSettingsDict( + sample_up="bfill", + sample_down="mean", + fill_nan=0.0, + fill_before=0.0, + fill_after=0.0, + ), + "waterlevel": StressSettingsDict( + sample_up="interpolate", + sample_down="mean", + fill_before="mean", + fill_after="mean", + fill_nan="interpolate", + ), + "level": StressSettingsDict( + sample_up="interpolate", + sample_down="mean", + fill_before="mean", + fill_after="mean", + fill_nan="interpolate", + ), + "flux": StressSettingsDict( + sample_up="bfill", + sample_down="mean", + fill_before="mean", + fill_after="mean", + fill_nan=0.0, + ), + "quantity": StressSettingsDict( + sample_up="divide", + sample_down="sum", + fill_before="mean", + fill_after="mean", + fill_nan=0.0, + ), } } diff --git a/pastas/stressmodels.py b/pastas/stressmodels.py index 33a4b17ac..3fa4fe96e 100644 --- a/pastas/stressmodels.py +++ b/pastas/stressmodels.py @@ -23,7 +23,14 @@ from pandas import DataFrame, Series, Timedelta, Timestamp, concat, date_range from scipy.signal import fftconvolve -from pastas.typing import ArrayLike, Model, Recharge, RFunc, TimestampType +from pastas.typing import ( + ArrayLike, + Model, + Recharge, + RFunc, + StressSettingsDict, + TimestampType, +) from .decorators import njit, set_parameter from .recharge import Linear @@ -233,7 +240,6 @@ def get_settings(self) -> dict: Notes ----- To update the settings of the time series, use the `update_stress` method. - """ if len(self.stress) == 0: settings = None @@ -258,9 +264,9 @@ class StressModel(StressModelBase): you don't want to define if response is positive or negative. settings: dict or str, optional The settings of the stress. This can be a string referring to a predefined - settings dict (defined in ps.rcParams["timeseries"]), or a dict with the - settings to apply. Refer to the docs of pastas.Timeseries for further - information. + settings dictionary (defined in ps.rcParams["timeseries"]), or a dictionary with + the settings to apply. For more information refer to Time series settings + section below. metadata: dict, optional dictionary containing metadata about the stress. This is passed onto the TimeSeries object. @@ -275,6 +281,47 @@ class StressModel(StressModelBase): >>> sm = ps.StressModel(stress=pd.Series(), rfunc=ps.Gamma(), name="Prec", >>> settings="prec") + Time series settings + -------------------- + Time series settings is a dictionary defining logic for filling and up- or + downsampling time series. + + fill_nan : {"drop", "mean", "interpolate"} or float + Method for filling NaNs. + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 + fill_before : {"mean", "bfill"} or float + Method for extending time series into past. + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 + fill_after : {"mean", "ffill"} or float + Method for extending time series into future. + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 + sample_up : {"mean", "interpolate", "divide"} or float + Method for up-sampling time series (increasing frequency, e.g. going from weekly + to daily values). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). + sample_down : {"mean", "drop", "sum", "min", "max"} + Method for down-sampling time series (decreasing frequency, e.g. going from + daily to weekly values). + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value + See Also -------- pastas.rfunc @@ -289,7 +336,7 @@ def __init__( rfunc: RFunc, name: str, up: bool = True, - settings: Optional[Union[dict, str]] = None, + settings: Optional[Union[str, StressSettingsDict]] = None, metadata: Optional[dict] = None, gain_scale_factor: Optional[float] = None, ) -> None: @@ -365,7 +412,6 @@ def to_dict(self, series: bool = True) -> dict: Notes ----- Settings and metadata are exported with the stress. - """ data = { "class": self._name, @@ -469,7 +515,6 @@ def to_dict(self, **kwargs) -> dict: ------- data: dict dictionary with all necessary information to reconstruct object. - """ data = { "class": self._name, @@ -583,7 +628,6 @@ def to_dict(self, **kwargs) -> dict: Returns ------- data: dict - """ data = { "class": self._name, @@ -669,12 +713,53 @@ class WellModel(StressModelBase): level. settings: str, list of dict, optional The settings of the stress. By default this is "well". This can be a string - referring to a predefined settings dict (defined in - ps.rcParams["timeseries"]), or a dict with the settings to apply. Refer - to the docs of pastas.Timeseries for further information. + referring to a predefined settings dictionary (defined in + ps.rcParams["timeseries"]), or a dictionary with the settings to apply. For more + information, refer to Time series settings section below. sort_wells: bool, optional sort wells from closest to furthest, by default True. + Time series settings + -------------------- + Time series settings is a dictionary defining logic for filling and up- or + downsampling time series. + + fill_nan : {"drop", "mean", "interpolate"} or float + Method for filling NaNs. + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 + fill_before : {"mean", "bfill"} or float + Method for extending time series into past. + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 + fill_after : {"mean", "ffill"} or float + Method for extending time series into future. + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 + sample_up : {"mean", "interpolate", "divide"} or float + Method for up-sampling time series (increasing frequency, e.g. going from weekly + to daily values). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). + sample_down : {"mean", "drop", "sum", "min", "max"} + Method for down-sampling time series (decreasing frequency, e.g. going from + daily to weekly values). + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value + Notes ----- This class implements convolution of multiple series with the same response @@ -694,7 +779,7 @@ def __init__( distances: ArrayLike, rfunc: Optional[RFunc] = None, up: bool = False, - settings: str = "well", + settings: Union[str, StressSettingsDict] = "well", sort_wells: bool = True, metadata: Optional[list] = None, ) -> None: @@ -901,7 +986,6 @@ def get_parameters(self, model=None, istress: Optional[int] = None) -> ArrayLike p : array_like parameters for each stress as row of array, if istress is used returns only one row. - """ if model is None: p = self.parameters.initial.values @@ -1039,35 +1123,71 @@ class RechargeModel(StressModelBase): It depends on the recharge model if this argument is required or not. The temperature series should be provided in degrees Celsius. settings: list of dicts or str, optional - The settings of the precipitation and evaporation time series, in this order. - This can be a string referring to a predefined settings dict (defined in - ps.rcParams["timeseries"]), or a dict with the settings to apply. Refer to - the docs of pastas.Timeseries for further information. + The settings of the precipitation, evaporation and optionally temperature time + series, in this order. By default ("prec", "evap", "evap"). This can be a string + referring to a predefined settings dict (defined in ps.rcParams["timeseries"]), + or a dict with the settings to apply. For more information refer to Time Series + Settings section below for more information. metadata: tuple of dicts or list of dicts, optional dictionary containing metadata about the stress. This is passed onto the TimeSeries object. - See Also + Examples -------- - pastas.rfunc - pastas.timeseries.TimeSeries - pastas.recharge + >>> sm = ps.RechargeModel(rain, evap, rfunc=ps.Exponential(), + >>> recharge=ps.rch.FlexModel(), name="rch") + >>> ml.add_stressmodel(sm) + + Time series settings + -------------------- + Time series settings is a dictionary defining logic for filling and up- or + downsampling time series. + + fill_nan : {"drop", "mean", "interpolate"} or float + Method for filling NaNs. + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 + fill_before : {"mean", "bfill"} or float + Method for extending time series into past. + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 + fill_after : {"mean", "ffill"} or float + Method for extending time series into future. + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 + sample_up : {"mean", "interpolate", "divide"} or float + Method for up-sampling time series (increasing frequency, e.g. going from weekly + to daily values). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). + sample_down : {"mean", "drop", "sum", "min", "max"} + Method for down-sampling time series (decreasing frequency, e.g. going from + daily to weekly values). + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value Notes ----- This stress model computes the contribution of precipitation and potential evaporation in two steps. In the first step a recharge flux is computed by a model determined by the input argument `recharge`. In the second step this - recharge flux is convoluted with a response function to obtain the contribution + recharge flux is convolved with a response function to obtain the contribution of recharge to the groundwater levels. If a nonlinear recharge model is used, the precipitation should be in mm/d. - Examples - -------- - >>> sm = ps.RechargeModel(rain, evap, rfunc=ps.Exponential(), - >>> recharge=ps.rch.FlexModel(), name="rch") - >>> ml.add_stressmodel(sm) - Warnings -------- We recommend not to store a RechargeModel is a variable named `rm`. This name is @@ -1080,6 +1200,11 @@ class RechargeModel(StressModelBase): the precipitation series are in m/d instead of mm/d. Please check the units of the precipitation series. + See Also + -------- + pastas.rfunc + pastas.timeseries.TimeSeries + pastas.recharge """ _name = "RechargeModel" @@ -1092,7 +1217,11 @@ def __init__( name: str = "recharge", recharge: Optional[Recharge] = None, temp: Optional[Series] = None, - settings: Tuple[Union[str, dict], Union[str, dict], Union[str, dict]] = ( + settings: Tuple[ + Union[str, StressSettingsDict], + Union[str, StressSettingsDict], + Union[str, StressSettingsDict], + ] = ( "prec", "evap", "evap", @@ -1403,7 +1532,6 @@ def to_dict(self, series: bool = True) -> dict: Notes ----- Settings and metadata are exported with the stress. - """ data = { "class": self._name, @@ -1553,7 +1681,6 @@ def to_dict(self, series: bool = True) -> dict: Notes ----- Settings and metadata are exported with the stress. - """ data = super().to_dict(series) data["dmin"] = self.dmin @@ -1562,8 +1689,8 @@ def to_dict(self, series: bool = True) -> dict: @staticmethod def _check_stressmodel_compatibility(ml: Model) -> None: - """Internal method to check if no other stressmodels, a constants or a - transform is used.""" + """Internal method to check if no other stressmodels, a constants or a transform + is used.""" msg = ( "A TarsoModel cannot be combined with %s. Either remove the TarsoModel or " "the %s." @@ -1578,8 +1705,8 @@ def _check_stressmodel_compatibility(ml: Model) -> None: @staticmethod @njit def tarso(p: ArrayLike, r: ArrayLike, dt: float) -> ArrayLike: - """Calculates the head based on exponential decay of the previous timestep - and recharge, using two thresholds.""" + """Calculates the head based on exponential decay of the previous timestep and + recharge, using two thresholds.""" A0, a0, d0, A1, a1, d1 = p # calculate physical meaning of these parameters @@ -1646,12 +1773,53 @@ class ChangeModel(StressModelBase): settings: dict or str, optional The settings of the stress. This can be a string referring to a predefined settings dict (defined in ps.rcParams["timeseries"]), or a dict with the - settings to apply. Refer to the docs of pastas.Timeseries for further - information. + settings to apply. For more information, refer to the docs of pastas.Timeseries + for further information. metadata: dict, optional dictionary containing metadata about the stress. This is passed onto the TimeSeries object. + Time series settings + -------------------- + Time series settings is a dictionary defining logic for filling and up- or + downsampling time series. + + fill_nan : {"drop", "mean", "interpolate"} or float + Method for filling NaNs. + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 + fill_before : {"mean", "bfill"} or float + Method for extending time series into past. + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 + fill_after : {"mean", "ffill"} or float + Method for extending time series into future. + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 + sample_up : {"mean", "interpolate", "divide"} or float + Method for up-sampling time series (increasing frequency, e.g. going from weekly + to daily values). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). + sample_down : {"mean", "drop", "sum", "min", "max"} + Method for down-sampling time series (decreasing frequency, e.g. going from + daily to weekly values). + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value + Notes ----- This model is based on :cite:t:`obergfell_identification_2019`. @@ -1667,7 +1835,7 @@ def __init__( name: str, tchange: Union[str, TimestampType], up: bool = True, - settings: Optional[Union[dict, str]] = None, + settings: Optional[Union[str, StressSettingsDict]] = None, metadata: Optional[dict] = None, ) -> None: stress = TimeSeries(stress, settings=settings, metadata=metadata) @@ -1771,7 +1939,6 @@ def to_dict(self, series: bool = True): Notes ----- Settings and metadata are exported with the stress. - """ data = { "stress": self.stress[0].to_dict(series=series), diff --git a/pastas/timeseries.py b/pastas/timeseries.py index 92b37d026..295310e13 100644 --- a/pastas/timeseries.py +++ b/pastas/timeseries.py @@ -25,9 +25,10 @@ class TimeSeries: String with the name of the time series, if None is provided, pastas will try to derive the name from the series. settings: str or dict, optional - String with the name of one of the predefined settings (obtained through - ps.TimeSeries._predefined_settings.) or a dictionary with the settings to be - applied. This does not have to include all the settings arguments. + The settings of the stress. This can be a string referring to a predefined + settings dictionary (defined in ps.rcParams["timeseries"]), or a dictionary with + the settings to apply. For more information refer to Time series settings + section below. metadata: dict, optional Dictionary with metadata of the time series. @@ -43,6 +44,47 @@ class TimeSeries: >>> ps.rcParams["timeseries"] + Time series settings + -------------------- + Time series settings is a dictionary defining logic for filling and up- or + downsampling time series. + + fill_nan : {"drop", "mean", "interpolate"} or float + Method for filling NaNs. + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 + fill_before : {"mean", "bfill"} or float + Method for extending time series into past. + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 + fill_after : {"mean", "ffill"} or float + Method for extending time series into future. + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 + sample_up : {"mean", "interpolate", "divide"} or float + Method for up-sampling time series (increasing frequency, e.g. going from weekly + to daily values). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). + sample_down : {"mean", "drop", "sum", "min", "max"} + Method for down-sampling time series (decreasing frequency, e.g. going from + daily to weekly values). + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value + See Also -------- pastas.timeseries.TimeSeries.update_series @@ -597,7 +639,6 @@ def validate_stress(series: Series): -------- >>> ps.validate_stress(series) - """ return _validate_series(series, equidistant=True) @@ -635,7 +676,6 @@ def validate_oseries(series: Series): -------- >>> ps.validate_oseries(series) - """ return _validate_series(series, equidistant=False) @@ -659,7 +699,6 @@ def _validate_series(series: Series, equidistant: bool = True): ----- If any of these checks are not passed the method will throw an error that needs to be fixed by the user. - """ # Because we are friendly and allow 1D DataFrames if isinstance(series, pd.DataFrame): diff --git a/pastas/typing/__init__.py b/pastas/typing/__init__.py index 2eb85b6a2..24665819d 100644 --- a/pastas/typing/__init__.py +++ b/pastas/typing/__init__.py @@ -7,10 +7,12 @@ Function, Model, NoiseModel, + OseriesSettingsDict, Recharge, RFunc, Solver, StressModel, + StressSettingsDict, TimeSeries, TimestampType, ) diff --git a/pastas/typing/types.py b/pastas/typing/types.py index f84168fda..f4f22e418 100644 --- a/pastas/typing/types.py +++ b/pastas/typing/types.py @@ -1,7 +1,7 @@ # flake8: noqa # Type hinting for Pastas library # Typing -from typing import TYPE_CHECKING, Any, Callable, TypeVar, Union +from typing import TYPE_CHECKING, Any, Callable, TypedDict, TypeVar, Union # External libraries # Matplotlib @@ -36,3 +36,81 @@ CallBack = TypeVar("CallBack", bound=Any) # Callback Function = Callable[..., Any] # Function (e.g. Objective Function) RFunc = TypeVar("RFunc", bound="ps.rfunc.RfuncBase") # rFunc Base + + +class OseriesSettingsDict(TypedDict): + """ + Time series settings is a dictionary defining logic for filling and up- or + downsampling time series. + + Time series settings + -------------------- + fill_nan : {"drop", "mean", "interpolate"} or float + Method for filling NaNs. + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 + sample_down : {"drop", "mean", "sum", "min", "max"} + Method for down-sampling time series (decreasing frequency, e.g. going from + daily to weekly values). + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `mean`: resample time series by taking the mean + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value + """ + + sample_down: str + fill_nan: str + + +class StressSettingsDict(TypedDict): + """ + Time series settings is a dictionary defining logic for filling and up- or + downsampling time series. + + Time series settings + -------------------- + fill_nan : {"drop", "mean", "interpolate"} or float + Method for filling NaNs. + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 + fill_before : {"mean", "bfill"} or float + Method for extending time series into past. + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 + fill_after : {"mean", "ffill"} or float + Method for extending time series into future. + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 + sample_up : {"mean", "interpolate", "divide"} or float + Method for up-sampling time series (increasing frequency, e.g. going from weekly + to daily values). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). + sample_down : {"mean", "drop", "sum", "min", "max"} + Method for down-sampling time series (decreasing frequency, e.g. going from + daily to weekly values). + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value + """ + + sample_up: str + sample_down: str + fill_nan: Union[str, float] + fill_before: Union[str, float] + fill_after: Union[str, float] From 5e77e04598249347e57fa07105d81cc30a4b5319 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Wed, 6 Sep 2023 11:30:03 +0200 Subject: [PATCH 02/10] fix isort check --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index d1585baf4..7bea1eee2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -119,7 +119,7 @@ legacy_tox_ini = """ extras = formatting commands = black pastas --check --diff - isort pastas --diff --profile=black + isort pastas --check --diff --profile=black [testenv:lint] description = run linters From b348e59573a22133b7e6189837f5897589f6be9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Wed, 6 Sep 2023 11:30:23 +0200 Subject: [PATCH 03/10] isort --- pastas/__init__.py | 5 +++-- pastas/objective_functions.py | 2 +- pastas/solver.py | 1 - 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pastas/__init__.py b/pastas/__init__.py index cd272c95b..933d36e6d 100644 --- a/pastas/__init__.py +++ b/pastas/__init__.py @@ -3,10 +3,12 @@ from pandas.plotting import register_matplotlib_converters +import pastas.objective_functions as objfunc import pastas.plots as plots import pastas.recharge as rch import pastas.stats as stats import pastas.timeseries_utils as ts + from .decorators import set_use_numba from .model import Model from .modelcompare import CompareModels @@ -25,8 +27,7 @@ Polder, Spline, ) -from .solver import LeastSquares, LmfitSolve, EmceeSolve -import pastas.objective_functions as objfunc +from .solver import EmceeSolve, LeastSquares, LmfitSolve from .stressmodels import ( ChangeModel, Constant, diff --git a/pastas/objective_functions.py b/pastas/objective_functions.py index c0b66a9e9..66bac17bf 100644 --- a/pastas/objective_functions.py +++ b/pastas/objective_functions.py @@ -2,7 +2,7 @@ `EmceeSolve` solver. """ -from numpy import pi, log +from numpy import log, pi from pandas import DataFrame diff --git a/pastas/solver.py b/pastas/solver.py index 7154f56df..c567eff35 100644 --- a/pastas/solver.py +++ b/pastas/solver.py @@ -20,7 +20,6 @@ from scipy.linalg import svd from scipy.optimize import least_squares - from pastas.objective_functions import GaussianLikelihood from pastas.typing import ArrayLike, CallBack, Function, Model From 310d1f7bc4b272a598b5930b196009296f019b7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Wed, 6 Sep 2023 14:51:44 +0200 Subject: [PATCH 04/10] black --- pastas/stressmodels.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pastas/stressmodels.py b/pastas/stressmodels.py index 3fa4fe96e..055c9807a 100644 --- a/pastas/stressmodels.py +++ b/pastas/stressmodels.py @@ -265,7 +265,7 @@ class StressModel(StressModelBase): settings: dict or str, optional The settings of the stress. This can be a string referring to a predefined settings dictionary (defined in ps.rcParams["timeseries"]), or a dictionary with - the settings to apply. For more information refer to Time series settings + the settings to apply. For more information refer to Time series settings section below. metadata: dict, optional dictionary containing metadata about the stress. This is passed onto the From 1e3886fb6e11ea3b99cae9e1238cb63b4e7532d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Thu, 7 Sep 2023 16:55:49 +0200 Subject: [PATCH 05/10] add custom section to docs --- doc/conf.py | 2 ++ pastas/utils.py | 24 ++++++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 9bf90ea6b..4f0cec77b 100755 --- a/doc/conf.py +++ b/doc/conf.py @@ -119,6 +119,8 @@ "ml": "pastas.model.Model", "TimestampType": "pandas.Timestamp", } +# add custom section to docstrings in Parameters style +napoleon_custom_sections = [("Time series settings", "params_style")] # -- Autodoc, autosummary, and autosectionlabel settings ------------------------------ diff --git a/pastas/utils.py b/pastas/utils.py index d909e00bf..2523755e7 100644 --- a/pastas/utils.py +++ b/pastas/utils.py @@ -207,3 +207,27 @@ def validate_name(name: str, raise_error: bool = False) -> str: logger.warning(msg) return name + + +def register_plotly_extension(): + from pastas.plotting.plotly import Plotly + + logger.info( + "Registered plotly plotting methods in Model class, e.g. `ml.plotly.plot()`." + ) + + +def register_plugin(module, target="plugins"): + import pastas as ps + + objs = [o for o in dir(module) if not o.startswith("_")] + if target is not None: + try: + target = getattr(ps, target) + except AttributeError: + setattr(ps, target, module) + target = getattr(ps, target) + else: + target = ps + for obj in objs: + setattr(target, obj, getattr(module, obj)) From 3a366521448d6f3ea6816a9623d589b8bf1fc66e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Sun, 10 Sep 2023 17:18:26 +0200 Subject: [PATCH 06/10] improve docs --- pastas/stressmodels.py | 210 +++++++++++++++++++---------------------- pastas/timeseries.py | 63 ++++++------- pastas/typing/types.py | 64 ++++++------- 3 files changed, 161 insertions(+), 176 deletions(-) diff --git a/pastas/stressmodels.py b/pastas/stressmodels.py index 055c9807a..dfbc84c57 100644 --- a/pastas/stressmodels.py +++ b/pastas/stressmodels.py @@ -274,53 +274,50 @@ class StressModel(StressModelBase): the scale factor is used to set the initial value and the bounds of the gain parameter, computed as 1 / gain_scale_factor. - Examples - -------- - >>> import pastas as ps - >>> import pandas as pd - >>> sm = ps.StressModel(stress=pd.Series(), rfunc=ps.Gamma(), name="Prec", - >>> settings="prec") - Time series settings -------------------- - Time series settings is a dictionary defining logic for filling and up- or - downsampling time series. - fill_nan : {"drop", "mean", "interpolate"} or float Method for filling NaNs. - * `drop`: drop NaNs from time series - * `mean`: fill NaNs with mean value of time series - * `interpolate`: fill NaNs by interpolating between finite values - * `float`: fill NaN with provided value, e.g. 0.0 + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 fill_before : {"mean", "bfill"} or float Method for extending time series into past. - * `mean`: extend time series into past with mean value of time series - * `bfill`: extend time series into past by back-filling first value - * `float`: extend time series into past with provided value, e.g. 0.0 + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 fill_after : {"mean", "ffill"} or float Method for extending time series into future. - * `mean`: extend time series into future with mean value of time series - * `ffill`: extend time series into future by forward-filling last value - * `float`: extend time series into future with provided value, e.g. 0.0 + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 sample_up : {"mean", "interpolate", "divide"} or float Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). - * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values - * `mean`: fill up-sampled time steps with mean of timeseries - * `interpolate`: fill up-sampled time steps by interpolating between current - values - * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). - * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values - * `sum`: resample time series by summing values - * `max`: resample time series with maximum value - * `min`: resample time series with minimum value + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value + + Examples + -------- + >>> import pastas as ps + >>> import pandas as pd + >>> sm = ps.StressModel(stress=pd.Series(), rfunc=ps.Gamma(), name="Prec", + >>> settings="prec") See Also -------- @@ -721,44 +718,41 @@ class WellModel(StressModelBase): Time series settings -------------------- - Time series settings is a dictionary defining logic for filling and up- or - downsampling time series. - fill_nan : {"drop", "mean", "interpolate"} or float Method for filling NaNs. - * `drop`: drop NaNs from time series - * `mean`: fill NaNs with mean value of time series - * `interpolate`: fill NaNs by interpolating between finite values - * `float`: fill NaN with provided value, e.g. 0.0 + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 fill_before : {"mean", "bfill"} or float Method for extending time series into past. - * `mean`: extend time series into past with mean value of time series - * `bfill`: extend time series into past by back-filling first value - * `float`: extend time series into past with provided value, e.g. 0.0 + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 fill_after : {"mean", "ffill"} or float Method for extending time series into future. - * `mean`: extend time series into future with mean value of time series - * `ffill`: extend time series into future by forward-filling last value - * `float`: extend time series into future with provided value, e.g. 0.0 + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 sample_up : {"mean", "interpolate", "divide"} or float Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). - * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values - * `mean`: fill up-sampled time steps with mean of timeseries - * `interpolate`: fill up-sampled time steps by interpolating between current - values - * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). - * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values - * `sum`: resample time series by summing values - * `max`: resample time series with maximum value - * `min`: resample time series with minimum value + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value Notes ----- @@ -1140,44 +1134,41 @@ class RechargeModel(StressModelBase): Time series settings -------------------- - Time series settings is a dictionary defining logic for filling and up- or - downsampling time series. - fill_nan : {"drop", "mean", "interpolate"} or float Method for filling NaNs. - * `drop`: drop NaNs from time series - * `mean`: fill NaNs with mean value of time series - * `interpolate`: fill NaNs by interpolating between finite values - * `float`: fill NaN with provided value, e.g. 0.0 + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 fill_before : {"mean", "bfill"} or float Method for extending time series into past. - * `mean`: extend time series into past with mean value of time series - * `bfill`: extend time series into past by back-filling first value - * `float`: extend time series into past with provided value, e.g. 0.0 + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 fill_after : {"mean", "ffill"} or float Method for extending time series into future. - * `mean`: extend time series into future with mean value of time series - * `ffill`: extend time series into future by forward-filling last value - * `float`: extend time series into future with provided value, e.g. 0.0 + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 sample_up : {"mean", "interpolate", "divide"} or float Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). - * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values - * `mean`: fill up-sampled time steps with mean of timeseries - * `interpolate`: fill up-sampled time steps by interpolating between current - values - * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). - * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values - * `sum`: resample time series by summing values - * `max`: resample time series with maximum value - * `min`: resample time series with minimum value + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value Notes ----- @@ -1781,44 +1772,41 @@ class ChangeModel(StressModelBase): Time series settings -------------------- - Time series settings is a dictionary defining logic for filling and up- or - downsampling time series. - fill_nan : {"drop", "mean", "interpolate"} or float Method for filling NaNs. - * `drop`: drop NaNs from time series - * `mean`: fill NaNs with mean value of time series - * `interpolate`: fill NaNs by interpolating between finite values - * `float`: fill NaN with provided value, e.g. 0.0 + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 fill_before : {"mean", "bfill"} or float Method for extending time series into past. - * `mean`: extend time series into past with mean value of time series - * `bfill`: extend time series into past by back-filling first value - * `float`: extend time series into past with provided value, e.g. 0.0 + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 fill_after : {"mean", "ffill"} or float Method for extending time series into future. - * `mean`: extend time series into future with mean value of time series - * `ffill`: extend time series into future by forward-filling last value - * `float`: extend time series into future with provided value, e.g. 0.0 + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 sample_up : {"mean", "interpolate", "divide"} or float Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). - * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values - * `mean`: fill up-sampled time steps with mean of timeseries - * `interpolate`: fill up-sampled time steps by interpolating between current - values - * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). - * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values - * `sum`: resample time series by summing values - * `max`: resample time series with maximum value - * `min`: resample time series with minimum value + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value Notes ----- diff --git a/pastas/timeseries.py b/pastas/timeseries.py index 295310e13..912833319 100644 --- a/pastas/timeseries.py +++ b/pastas/timeseries.py @@ -37,53 +37,50 @@ class TimeSeries: series: pastas.TimeSeries Returns a pastas.TimeSeries object. - Examples - -------- - To obtain the predefined TimeSeries settings, you can run the following line of - code: - - >>> ps.rcParams["timeseries"] - Time series settings -------------------- - Time series settings is a dictionary defining logic for filling and up- or - downsampling time series. - fill_nan : {"drop", "mean", "interpolate"} or float Method for filling NaNs. - * `drop`: drop NaNs from time series - * `mean`: fill NaNs with mean value of time series - * `interpolate`: fill NaNs by interpolating between finite values - * `float`: fill NaN with provided value, e.g. 0.0 + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 fill_before : {"mean", "bfill"} or float Method for extending time series into past. - * `mean`: extend time series into past with mean value of time series - * `bfill`: extend time series into past by back-filling first value - * `float`: extend time series into past with provided value, e.g. 0.0 + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 fill_after : {"mean", "ffill"} or float Method for extending time series into future. - * `mean`: extend time series into future with mean value of time series - * `ffill`: extend time series into future by forward-filling last value - * `float`: extend time series into future with provided value, e.g. 0.0 + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 sample_up : {"mean", "interpolate", "divide"} or float Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). - * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values - * `mean`: fill up-sampled time steps with mean of timeseries - * `interpolate`: fill up-sampled time steps by interpolating between current - values - * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). - * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values - * `sum`: resample time series by summing values - * `max`: resample time series with maximum value - * `min`: resample time series with minimum value + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value + + Examples + -------- + To obtain the predefined TimeSeries settings, you can run the following line of + code: + + >>> ps.rcParams["timeseries"] See Also -------- diff --git a/pastas/typing/types.py b/pastas/typing/types.py index f4f22e418..adc965539 100644 --- a/pastas/typing/types.py +++ b/pastas/typing/types.py @@ -47,18 +47,18 @@ class OseriesSettingsDict(TypedDict): -------------------- fill_nan : {"drop", "mean", "interpolate"} or float Method for filling NaNs. - * `drop`: drop NaNs from time series - * `mean`: fill NaNs with mean value of time series - * `interpolate`: fill NaNs by interpolating between finite values - * `float`: fill NaN with provided value, e.g. 0.0 + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 sample_down : {"drop", "mean", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). - * `drop`: resample the time series by taking the mean, dropping any NaN-values - * `mean`: resample time series by taking the mean - * `sum`: resample time series by summing values - * `max`: resample time series with maximum value - * `min`: resample time series with minimum value + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `mean`: resample time series by taking the mean + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value """ sample_down: str @@ -74,39 +74,39 @@ class StressSettingsDict(TypedDict): -------------------- fill_nan : {"drop", "mean", "interpolate"} or float Method for filling NaNs. - * `drop`: drop NaNs from time series - * `mean`: fill NaNs with mean value of time series - * `interpolate`: fill NaNs by interpolating between finite values - * `float`: fill NaN with provided value, e.g. 0.0 + * `drop`: drop NaNs from time series + * `mean`: fill NaNs with mean value of time series + * `interpolate`: fill NaNs by interpolating between finite values + * `float`: fill NaN with provided value, e.g. 0.0 fill_before : {"mean", "bfill"} or float Method for extending time series into past. - * `mean`: extend time series into past with mean value of time series - * `bfill`: extend time series into past by back-filling first value - * `float`: extend time series into past with provided value, e.g. 0.0 + * `mean`: extend time series into past with mean value of time series + * `bfill`: extend time series into past by back-filling first value + * `float`: extend time series into past with provided value, e.g. 0.0 fill_after : {"mean", "ffill"} or float Method for extending time series into future. - * `mean`: extend time series into future with mean value of time series - * `ffill`: extend time series into future by forward-filling last value - * `float`: extend time series into future with provided value, e.g. 0.0 + * `mean`: extend time series into future with mean value of time series + * `ffill`: extend time series into future by forward-filling last value + * `float`: extend time series into future with provided value, e.g. 0.0 sample_up : {"mean", "interpolate", "divide"} or float Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). - * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values - * `mean`: fill up-sampled time steps with mean of timeseries - * `interpolate`: fill up-sampled time steps by interpolating between current - values - * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + * `bfill` or `backfill`: fill up-sampled time steps by back-filling current + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + * `mean`: fill up-sampled time steps with mean of timeseries + * `interpolate`: fill up-sampled time steps by interpolating between current + values + * `divide`: fill up-sampled steps with current value divided by length of + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). - * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values - * `sum`: resample time series by summing values - * `max`: resample time series with maximum value - * `min`: resample time series with minimum value + * `mean`: resample time series by taking the mean + * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `sum`: resample time series by summing values + * `max`: resample time series with maximum value + * `min`: resample time series with minimum value """ sample_up: str From 33bb517945e991d04b0d26865abd1a82b9d8aed6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Sun, 10 Sep 2023 19:34:41 +0200 Subject: [PATCH 07/10] update docs --- pastas/stressmodels.py | 40 ++++++++++++++++++++++++---------------- pastas/timeseries.py | 10 ++++++---- pastas/typing/types.py | 10 ++++++---- 3 files changed, 36 insertions(+), 24 deletions(-) diff --git a/pastas/stressmodels.py b/pastas/stressmodels.py index dfbc84c57..a9823aad2 100644 --- a/pastas/stressmodels.py +++ b/pastas/stressmodels.py @@ -296,18 +296,20 @@ class StressModel(StressModelBase): Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current + values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current - values + values * `divide`: fill up-sampled steps with current value divided by length of current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `drop`: resample the time series by taking the mean, dropping any + NaN-values * `sum`: resample time series by summing values * `max`: resample time series with maximum value * `min`: resample time series with minimum value @@ -738,18 +740,20 @@ class WellModel(StressModelBase): Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current + values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current - values + values * `divide`: fill up-sampled steps with current value divided by length of current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `drop`: resample the time series by taking the mean, dropping any + NaN-values * `sum`: resample time series by summing values * `max`: resample time series with maximum value * `min`: resample time series with minimum value @@ -1154,18 +1158,20 @@ class RechargeModel(StressModelBase): Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current + values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current - values + values * `divide`: fill up-sampled steps with current value divided by length of current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `drop`: resample the time series by taking the mean, dropping any + NaN-values * `sum`: resample time series by summing values * `max`: resample time series with maximum value * `min`: resample time series with minimum value @@ -1792,18 +1798,20 @@ class ChangeModel(StressModelBase): Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current + values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current - values + values * `divide`: fill up-sampled steps with current value divided by length of current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `drop`: resample the time series by taking the mean, dropping any + NaN-values * `sum`: resample time series by summing values * `max`: resample time series with maximum value * `min`: resample time series with minimum value diff --git a/pastas/timeseries.py b/pastas/timeseries.py index 912833319..b79835cee 100644 --- a/pastas/timeseries.py +++ b/pastas/timeseries.py @@ -59,18 +59,20 @@ class TimeSeries: Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current + values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current - values + values * `divide`: fill up-sampled steps with current value divided by length of current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `drop`: resample the time series by taking the mean, dropping any + NaN-values * `sum`: resample time series by summing values * `max`: resample time series with maximum value * `min`: resample time series with minimum value diff --git a/pastas/typing/types.py b/pastas/typing/types.py index adc965539..e553cf4ef 100644 --- a/pastas/typing/types.py +++ b/pastas/typing/types.py @@ -92,18 +92,20 @@ class StressSettingsDict(TypedDict): Method for up-sampling time series (increasing frequency, e.g. going from weekly to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current - values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current values + values + * `ffill or `pad`: fill up-sampled time steps by forward-filling current + values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current - values + values * `divide`: fill up-sampled steps with current value divided by length of current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). * `mean`: resample time series by taking the mean - * `drop`: resample the time series by taking the mean, dropping any NaN-values + * `drop`: resample the time series by taking the mean, dropping any + NaN-values * `sum`: resample time series by summing values * `max`: resample time series with maximum value * `min`: resample time series with minimum value From 2e80a524daafe393b814f50a37773573a104bab3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Sun, 10 Sep 2023 19:58:24 +0200 Subject: [PATCH 08/10] update docs --- pastas/stressmodels.py | 8 ++++---- pastas/timeseries.py | 2 +- pastas/typing/types.py | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pastas/stressmodels.py b/pastas/stressmodels.py index a9823aad2..d6f6acce7 100644 --- a/pastas/stressmodels.py +++ b/pastas/stressmodels.py @@ -297,7 +297,7 @@ class StressModel(StressModelBase): to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current + * `ffill` or `pad`: fill up-sampled time steps by forward-filling current values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current @@ -741,7 +741,7 @@ class WellModel(StressModelBase): to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current + * `ffill` or `pad`: fill up-sampled time steps by forward-filling current values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current @@ -1159,7 +1159,7 @@ class RechargeModel(StressModelBase): to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current + * `ffill` or `pad`: fill up-sampled time steps by forward-filling current values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current @@ -1799,7 +1799,7 @@ class ChangeModel(StressModelBase): to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current + * `ffill` or `pad`: fill up-sampled time steps by forward-filling current values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current diff --git a/pastas/timeseries.py b/pastas/timeseries.py index b79835cee..c11ea5848 100644 --- a/pastas/timeseries.py +++ b/pastas/timeseries.py @@ -60,7 +60,7 @@ class TimeSeries: to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current + * `ffill` or `pad`: fill up-sampled time steps by forward-filling current values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current diff --git a/pastas/typing/types.py b/pastas/typing/types.py index e553cf4ef..98c51ea50 100644 --- a/pastas/typing/types.py +++ b/pastas/typing/types.py @@ -93,7 +93,7 @@ class StressSettingsDict(TypedDict): to daily values). * `bfill` or `backfill`: fill up-sampled time steps by back-filling current values - * `ffill or `pad`: fill up-sampled time steps by forward-filling current + * `ffill` or `pad`: fill up-sampled time steps by forward-filling current values * `mean`: fill up-sampled time steps with mean of timeseries * `interpolate`: fill up-sampled time steps by interpolating between current From 8ff8a199e000df46e0c7a83901c9cfc9db18189d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Mon, 11 Sep 2023 14:16:03 +0200 Subject: [PATCH 09/10] update docs --- pastas/stressmodels.py | 8 ++++---- pastas/timeseries.py | 2 +- pastas/typing/types.py | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pastas/stressmodels.py b/pastas/stressmodels.py index d6f6acce7..e880b8070 100644 --- a/pastas/stressmodels.py +++ b/pastas/stressmodels.py @@ -303,7 +303,7 @@ class StressModel(StressModelBase): * `interpolate`: fill up-sampled time steps by interpolating between current values * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). @@ -747,7 +747,7 @@ class WellModel(StressModelBase): * `interpolate`: fill up-sampled time steps by interpolating between current values * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). @@ -1165,7 +1165,7 @@ class RechargeModel(StressModelBase): * `interpolate`: fill up-sampled time steps by interpolating between current values * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). @@ -1805,7 +1805,7 @@ class ChangeModel(StressModelBase): * `interpolate`: fill up-sampled time steps by interpolating between current values * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). diff --git a/pastas/timeseries.py b/pastas/timeseries.py index c11ea5848..08fd87193 100644 --- a/pastas/timeseries.py +++ b/pastas/timeseries.py @@ -66,7 +66,7 @@ class TimeSeries: * `interpolate`: fill up-sampled time steps by interpolating between current values * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). diff --git a/pastas/typing/types.py b/pastas/typing/types.py index 98c51ea50..fb3810b74 100644 --- a/pastas/typing/types.py +++ b/pastas/typing/types.py @@ -99,7 +99,7 @@ class StressSettingsDict(TypedDict): * `interpolate`: fill up-sampled time steps by interpolating between current values * `divide`: fill up-sampled steps with current value divided by length of - current time steps (i.e. spread value over new time steps). + current time steps (i.e. spread value over new time steps). sample_down : {"mean", "drop", "sum", "min", "max"} Method for down-sampling time series (decreasing frequency, e.g. going from daily to weekly values). From 4cdd1917379960465659e5cec65c01d4705e092c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dav=C3=ADd=20Brakenhoff?= Date: Mon, 18 Sep 2023 10:18:35 +0200 Subject: [PATCH 10/10] remove unrelated code from PR --- pastas/utils.py | 24 ------------------------ 1 file changed, 24 deletions(-) diff --git a/pastas/utils.py b/pastas/utils.py index 2523755e7..d909e00bf 100644 --- a/pastas/utils.py +++ b/pastas/utils.py @@ -207,27 +207,3 @@ def validate_name(name: str, raise_error: bool = False) -> str: logger.warning(msg) return name - - -def register_plotly_extension(): - from pastas.plotting.plotly import Plotly - - logger.info( - "Registered plotly plotting methods in Model class, e.g. `ml.plotly.plot()`." - ) - - -def register_plugin(module, target="plugins"): - import pastas as ps - - objs = [o for o in dir(module) if not o.startswith("_")] - if target is not None: - try: - target = getattr(ps, target) - except AttributeError: - setattr(ps, target, module) - target = getattr(ps, target) - else: - target = ps - for obj in objs: - setattr(target, obj, getattr(module, obj))