pastastore 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

pastastore/store.py

@@ -1,7 +1,9 @@
+"""Module containing the PastaStore object for managing time series and models."""
+
 import json
 import os
 import warnings
-from typing import List, Optional, Tuple, Union
+from typing import List, Literal, Optional, Tuple, Union
 
 import numpy as np
 import pandas as pd
@@ -14,6 +16,7 @@ from pastastore.base import BaseConnector
 from pastastore.connectors import DictConnector
 from pastastore.plotting import Maps, Plots
 from pastastore.util import _custom_warning
+from pastastore.version import PASTAS_GEQ_150
 from pastastore.yaml_interface import PastastoreYAML
 
 FrameorSeriesUnion = Union[pd.DataFrame, pd.Series]
@@ -72,7 +75,7 @@ class PastaStore:
         self.yaml = PastastoreYAML(self)
 
     def _register_connector_methods(self):
-        """Internal method for registering connector methods."""
+        """Register connector methods (internal method)."""
         methods = [
             func
             for func in dir(self.conn)
@@ -83,26 +86,70 @@ class PastaStore:
 
     @property
     def oseries(self):
+        """
+        Returns the oseries metadata as dataframe.
+
+        Returns
+        -------
+        oseries
+            oseries metadata as dataframe
+        """
         return self.conn.oseries
 
     @property
     def stresses(self):
+        """
+        Returns the stresses metadata as dataframe.
+
+        Returns
+        -------
+        stresses
+            stresses metadata as dataframe
+        """
         return self.conn.stresses
 
     @property
     def models(self):
+        """Return list of model names.
+
+        Returns
+        -------
+        list
+            list of model names
+        """
         return self.conn.models
 
     @property
     def oseries_names(self):
+        """Return list of oseries names.
+
+        Returns
+        -------
+        list
+            list of oseries names
+        """
         return self.conn.oseries_names
 
     @property
     def stresses_names(self):
+        """Return list of streses names.
+
+        Returns
+        -------
+        list
+            list of stresses names
+        """
         return self.conn.stresses_names
 
     @property
     def model_names(self):
+        """Return list of model names.
+
+        Returns
+        -------
+        list
+            list of model names
+        """
         return self.conn.model_names
 
     @property
@@ -111,22 +158,57 @@ class PastaStore:
 
     @property
     def n_oseries(self):
+        """Return number of oseries.
+
+        Returns
+        -------
+        int
+            number of oseries
+        """
         return self.conn.n_oseries
 
     @property
     def n_stresses(self):
+        """Return number of stresses.
+
+        Returns
+        -------
+        int
+            number of stresses
+        """
         return self.conn.n_stresses
 
     @property
     def n_models(self):
+        """Return number of models.
+
+        Returns
+        -------
+        int
+            number of models
+        """
         return self.conn.n_models
 
     @property
     def oseries_models(self):
+        """Return dictionary of models per oseries.
+
+        Returns
+        -------
+        dict
+            dictionary containing list of models (values) for each oseries (keys).
+        """
         return self.conn.oseries_models
 
     @property
     def oseries_with_models(self):
+        """Return list of oseries for which models are contained in the database.
+
+        Returns
+        -------
+        list
+            list of oseries names for which models are contained in the database.
+        """
         return self.conn.oseries_with_models
 
     def __repr__(self):
@@ -136,7 +218,7 @@ class PastaStore:
     def get_oseries_distances(
         self, names: Optional[Union[list, str]] = None
     ) -> FrameorSeriesUnion:
-        """Method to obtain the distances in meters between the oseries.
+        """Get the distances in meters between the oseries.
 
         Parameters
         ----------
@@ -175,7 +257,7 @@ class PastaStore:
         n: int = 1,
         maxdist: Optional[float] = None,
     ) -> FrameorSeriesUnion:
-        """Method to obtain the nearest (n) oseries.
+        """Get the nearest (n) oseries.
 
         Parameters
         ----------
@@ -191,7 +273,6 @@ class PastaStore:
         oseries:
             list with the names of the oseries.
         """
-
         distances = self.get_oseries_distances(names)
         if maxdist is not None:
             distances = distances.where(distances <= maxdist, np.nan)
@@ -214,8 +295,7 @@ class PastaStore:
         stresses: Optional[Union[list, str]] = None,
         kind: Optional[Union[str, List[str]]] = None,
     ) -> FrameorSeriesUnion:
-        """Method to obtain the distances in meters between the oseries and
-        stresses.
+        """Get the distances in meters between the oseries and stresses.
 
         Parameters
         ----------
@@ -274,7 +354,7 @@ class PastaStore:
         n: int = 1,
         maxdist: Optional[float] = None,
     ) -> FrameorSeriesUnion:
-        """Method to obtain the nearest (n) stresses of a specific kind.
+        """Get the nearest (n) stresses of a specific kind.
 
         Parameters
         ----------
@@ -295,7 +375,6 @@ class PastaStore:
         stresses:
             list with the names of the stresses.
         """
-
         distances = self.get_distances(oseries, stresses, kind)
         if maxdist is not None:
             distances = distances.where(distances <= maxdist, np.nan)
@@ -317,8 +396,9 @@ class PastaStore:
         progressbar=False,
         ignore_errors=False,
     ):
-        """Get groundwater signatures. NaN-values are returned when the
-        signature could not be computed.
+        """Get groundwater signatures.
+
+        NaN-values are returned when the signature cannot be computed.
 
         Parameters
         ----------
@@ -384,7 +464,12 @@ class PastaStore:
 
         return signatures_df
 
-    def get_tmin_tmax(self, libname, names=None, progressbar=False):
+    def get_tmin_tmax(
+        self,
+        libname: Literal["oseries", "stresses", "models"],
+        names: Union[str, List[str], None] = None,
+        progressbar: bool = False,
+    ):
         """Get tmin and tmax for time series.
 
         Parameters
@@ -403,22 +488,48 @@ class PastaStore:
         tmintmax : pd.dataframe
             Dataframe containing tmin and tmax per time series
         """
-
         names = self.conn._parse_names(names, libname=libname)
         tmintmax = pd.DataFrame(
             index=names, columns=["tmin", "tmax"], dtype="datetime64[ns]"
         )
         desc = f"Get tmin/tmax {libname}"
         for n in tqdm(names, desc=desc) if progressbar else names:
-            if libname == "oseries":
-                s = self.conn.get_oseries(n)
+            if libname == "models":
+                mld = self.conn.get_models(
+                    n,
+                    return_dict=True,
+                )
+                tmintmax.loc[n, "tmin"] = mld["settings"]["tmin"]
+                tmintmax.loc[n, "tmax"] = mld["settings"]["tmax"]
             else:
-                s = self.conn.get_stresses(n)
-            tmintmax.loc[n, "tmin"] = s.first_valid_index()
-            tmintmax.loc[n, "tmax"] = s.last_valid_index()
+                s = (
+                    self.conn.get_oseries(n)
+                    if libname == "oseries"
+                    else self.conn.get_stresses(n)
+                )
+                tmintmax.loc[n, "tmin"] = s.first_valid_index()
+                tmintmax.loc[n, "tmax"] = s.last_valid_index()
+
         return tmintmax
 
     def get_extent(self, libname, names=None, buffer=0.0):
+        """Get extent [xmin, xmax, ymin, ymax] from library.
+
+        Parameters
+        ----------
+        libname : str
+            name of the library containing the time series
+            ('oseries', 'stresses', 'models')
+        names : str, list of str, or None, optional
+            list of names to include for computing the extent
+        buffer : float, optional
+            add this distance to the extent, by default 0.0
+
+        Returns
+        -------
+        extent : list
+            extent [xmin, xmax, ymin, ymax]
+        """
         names = self.conn._parse_names(names, libname=libname)
         if libname in ["oseries", "stresses"]:
             df = getattr(self, libname)
@@ -443,8 +554,10 @@ class PastaStore:
         progressbar: Optional[bool] = False,
         ignore_errors: Optional[bool] = False,
     ) -> FrameorSeriesUnion:
-        """Get model parameters. NaN-values are returned when the parameters
-        are not present in the model or the model is not optimized.
+        """Get model parameters.
+
+        NaN-values are returned when the parameters are not present in the model or the
+        model is not optimized.
 
         Parameters
         ----------
@@ -526,7 +639,6 @@ class PastaStore:
         -------
         s : pandas.DataFrame
         """
-
         modelnames = self.conn._parse_names(modelnames, libname="models")
 
         # if statistics is str
@@ -558,6 +670,7 @@ class PastaStore:
         name: str,
         modelname: str = None,
         add_recharge: bool = True,
+        add_ar_noisemodel: bool = False,
         recharge_name: str = "recharge",
     ) -> ps.Model:
         """Create a pastas Model.
@@ -572,6 +685,8 @@ class PastaStore:
             add recharge to the model by looking for the closest
             precipitation and evaporation time series in the stresses
             library, by default True
+        add_ar1_noisemodel : bool, optional
+            add AR(1) noise model to the model, by default False
         recharge_name : str
             name of the RechargeModel
 
@@ -598,6 +713,8 @@ class PastaStore:
             ml = ps.Model(ts, name=modelname, metadata=meta)
             if add_recharge:
                 self.add_recharge(ml, recharge_name=recharge_name)
+            if add_ar_noisemodel and PASTAS_GEQ_150:
+                ml.add_noisemodel(ps.ArNoiseModel())
             return ml
         else:
             raise ValueError("Empty time series!")
@@ -709,9 +826,9 @@ class PastaStore:
         for var in ("prec", "evap"):
             try:
                 name = self.get_nearest_stresses(ml.oseries.name, kind=var).iloc[0, 0]
-            except AttributeError:
+            except AttributeError as e:
                 msg = "No precipitation or evaporation time series found!"
-                raise Exception(msg)
+                raise Exception(msg) from e
             if isinstance(name, float):
                 if np.isnan(name):
                     raise ValueError(
@@ -828,8 +945,8 @@ class PastaStore:
         """
         try:
             from art_tools import pastas_get_model_results
-        except Exception:
-            raise ModuleNotFoundError("You need 'art_tools' to use this method!")
+        except Exception as e:
+            raise ModuleNotFoundError("You need 'art_tools' to use this method!") from e
 
         if mls is None:
             mls = self.conn.models
@@ -870,7 +987,7 @@ class PastaStore:
                 "File already exists! " "Use 'overwrite=True' to " "force writing file."
             )
         elif os.path.exists(fname):
-            warnings.warn(f"Overwriting file '{os.path.basename(fname)}'")
+            warnings.warn(f"Overwriting file '{os.path.basename(fname)}'", stacklevel=1)
 
         with ZipFile(fname, "w", compression=ZIP_DEFLATED) as archive:
             # oseries
@@ -1011,13 +1128,12 @@ class PastaStore:
         matches : list
             list of names that match search result
         """
-
         if libname == "models":
-            lib_names = getattr(self, "model_names")
+            lib_names = self.model_names
         elif libname == "stresses":
-            lib_names = getattr(self, "stresses_names")
+            lib_names = self.stresses_names
         elif libname == "oseries":
-            lib_names = getattr(self, "oseries_names")
+            lib_names = self.oseries_names
         else:
             raise ValueError("Provide valid libname: 'models', 'stresses' or 'oseries'")
 
@@ -1064,7 +1180,6 @@ class PastaStore:
             indicating whether a stress is contained within a time series
             model.
         """
-
         model_names = self.conn._parse_names(modelnames, libname="models")
         structure = pd.DataFrame(
             index=model_names, columns=["oseries"] + self.stresses_names
@@ -1138,6 +1253,23 @@ class PastaStore:
         return result
 
     def within(self, extent, names=None, libname="oseries"):
+        """Get names of items within extent.
+
+        Parameters
+        ----------
+        extent : list
+            list with [xmin, xmax, ymin, ymax]
+        names : str, list of str, optional
+            list of names to include, by default None
+        libname : str, optional
+            name of library, must be one of ('oseries', 'stresses', 'models'), by
+            default "oseries"
+
+        Returns
+        -------
+        list
+            list of items within extent
+        """
         xmin, xmax, ymin, ymax = extent
         names = self.conn._parse_names(names, libname)
         if libname == "oseries":

pastastore/styling.py

@@ -1,3 +1,5 @@
+"""Module containing dataframe styling functions."""
+
 import matplotlib as mpl
 import matplotlib.pyplot as plt
 import numpy as np
@@ -25,7 +27,6 @@ def float_styler(val, norm, cmap=None):
     Given some dataframe
 
     >>> df.map(float_styler, subset=["some column"], norm=norm, cmap=cmap)
-
     """
     if cmap is None:
         cmap = plt.get_cmap("RdYlBu")

pastastore/util.py

@@ -1,4 +1,7 @@
+"""Useful utilities for pastastore."""
+
 import os
+import warnings
 from typing import Dict, List, Optional, Union
 
 import numpy as np
@@ -16,9 +19,12 @@ def _custom_warning(message, category=UserWarning, filename="", lineno=-1, *args
 
 
 class ItemInLibraryException(Exception):
+    """Exception when item is already in library."""
+
     pass
 
 
+# TODO: remove in future version
 def delete_pystore_connector(
     conn=None,
     path: Optional[str] = None,
@@ -39,6 +45,12 @@ def delete_pystore_connector(
         list of library names to delete, by default None which deletes
         all libraries
     """
+    warnings.warn(
+        "This function is deprecated. We recommend to migrate to a different "
+        "Connector, e.g. `pst.PasConnector`.",
+        DeprecationWarning,
+        stacklevel=1,
+    )
     import pystore
 
     if conn is not None:
@@ -60,6 +72,7 @@ def delete_pystore_connector(
             print(f" - deleted: {lib}")
 
 
+# TODO: remove in future version
 def delete_arctic_connector(
     conn=None,
     connstr: Optional[str] = None,
@@ -80,6 +93,12 @@ def delete_arctic_connector(
         list of library names to delete, by default None which deletes
         all libraries
     """
+    warnings.warn(
+        "This function is deprecated. We recommend to migrate to a different "
+        "Connector, e.g. `pst.ArcticDBConnector`.",
+        DeprecationWarning,
+        stacklevel=1,
+    )
     import arctic
 
     if conn is not None:
@@ -172,6 +191,7 @@ def delete_arcticdb_connector(
 
 
 def delete_dict_connector(conn, libraries: Optional[List[str]] = None) -> None:
+    """Delete DictConnector object."""
     print(f"Deleting DictConnector: '{conn.name}' ... ", end="")
     if libraries is None:
         del conn
@@ -185,6 +205,7 @@ def delete_dict_connector(conn, libraries: Optional[List[str]] = None) -> None:
 
 
 def delete_pas_connector(conn, libraries: Optional[List[str]] = None) -> None:
+    """Delete PasConnector object."""
     import shutil
 
     print(f"Deleting PasConnector database: '{conn.name}' ... ", end="")
@@ -222,10 +243,12 @@ def delete_pastastore(pstore, libraries: Optional[List[str]] = None) -> None:
     TypeError
         when Connector type is not recognized
     """
+    # TODO: remove in future version
     if pstore.conn.conn_type == "pystore":
         delete_pystore_connector(conn=pstore.conn, libraries=libraries)
     elif pstore.conn.conn_type == "dict":
         delete_dict_connector(pstore)
+    # TODO: remove in future version
     elif pstore.conn.conn_type == "arctic":
         delete_arctic_connector(conn=pstore.conn, libraries=libraries)
     elif pstore.conn.conn_type == "arcticdb":
@@ -303,7 +326,6 @@ def compare_models(ml1, ml2, stats=None, detailed_comparison=False):
         returns True if models are equivalent when detailed_comparison=True
         else returns DataFrame containing comparison details.
     """
-
     df = pd.DataFrame(columns=["model 0", "model 1"])
     so1 = []  # for storing series_original
     sv1 = []  # for storing series_validated
@@ -552,6 +574,7 @@ def frontiers_checks(
     check4_gain: bool = True,
     check5_parambounds: bool = False,
     csv_dir: Optional[str] = None,
+    progressbar: bool = False,
 ) -> pd.DataFrame:  # pragma: no cover
     """Check models in a PastaStore to see if they pass reliability criteria.
 
@@ -597,6 +620,8 @@ def frontiers_checks(
     csv_dir : string, optional
         directory to store CSV file with overview of checks for every
         model, by default None which will not store results
+    progressbar : bool, optional
+        show progressbar, by default False
 
     Returns
     -------
@@ -612,7 +637,6 @@ def frontiers_checks(
     Application of Time Series Analysis to Estimate Drawdown From Multiple Well
     Fields. Front. Earth Sci., 14 June 2022 doi:10.3389/feart.2022.907609
     """
-
     df = pd.DataFrame(columns=["all_checks_passed"])
 
     if modelnames is not None:
@@ -629,7 +653,9 @@ def frontiers_checks(
     else:
         models = pstore.model_names
 
-    for mlnam in tqdm(models, desc="Running model diagnostics"):
+    for mlnam in (
+        tqdm(models, desc="Running model diagnostics") if progressbar else models
+    ):
         ml = pstore.get_models(mlnam)
 
         if ml.parameters["optimal"].hasnans:
@@ -734,7 +760,10 @@ def frontiers_checks(
                         else:
                             check_gain_passed = np.abs(gain) > 2 * gain_std
                         checks.loc[
-                            f"gain > 2*std: {sm_name}-{iw:02g} ({sm.distances.index[iw]})",
+                            (
+                                f"gain > 2*std: {sm_name}-{iw:02g}"
+                                f" ({sm.distances.index[iw]})"
+                            ),
                             :,
                         ] = (
                             gain,
@@ -829,7 +858,6 @@ def frontiers_aic_select(
     Multiple Well Fields. Front. Earth Sci., 14 June 2022
     doi:10.3389/feart.2022.907609
     """
-
     if modelnames is None and oseries is None:
         modelnames = pstore.model_names
     elif modelnames is None and oseries is not None:
@@ -853,7 +881,7 @@ def frontiers_aic_select(
         # with lowest AIC per location
         collect = []
         gr = df.join(aic).groupby("oseries")
-        for o, idf in gr:
+        for _, idf in gr:
             idf.index.name = "modelname"
             idf = (
                 idf.sort_values("aic").reset_index().set_index(["oseries", "modelname"])

pastastore/version.py

@@ -1,7 +1,38 @@
+# ruff: noqa: D100
+from importlib import import_module, metadata
+from platform import python_version
+
 import pastas as ps
 from packaging.version import parse as parse_version
 
 PASTAS_VERSION = parse_version(ps.__version__)
 PASTAS_LEQ_022 = PASTAS_VERSION <= parse_version("0.22.0")
+PASTAS_GEQ_150 = PASTAS_VERSION >= parse_version("1.5.0")
+
+__version__ = "1.5.0"
+
+
+def show_versions(optional=False) -> None:
+    """Print the version of dependencies.
+
+    Parameters
+    ----------
+    optional : bool, optional
+        Print the version of optional dependencies, by default False
+    """
+    msg = (
+        f"Python version     : {python_version()}\n"
+        f"Pandas version     : {metadata.version('pandas')}\n"
+        f"Matplotlib version : {metadata.version('matplotlib')}\n"
+        f"Pastas version     : {metadata.version('pastas')}\n"
+        f"PyYAML version     : {metadata.version('pyyaml')}\n"
+    )
+    if optional:
+        msg += "\nArcticDB version   : "
+        try:
+            import_module("arcticdb")
+            msg += f"{metadata.version('arctidb')}"
+        except ImportError:
+            msg += "Not Installed"
 
-__version__ = "1.4.0"
+    print(msg)