pastastore 1.8.0__py3-none-any.whl → 1.10.0__py3-none-any.whl

pastastore/base.py

@@ -332,7 +332,8 @@ class BaseConnector(ABC):
             self._clear_cache(libname)
         else:
             raise ItemInLibraryException(
-                f"Item with name '{name}' already" f" in '{libname}' library!"
+                f"Time series with name '{name}' already in '{libname}' library! "
+                "Use overwrite=True to replace existing time series."
             )
 
     def _update_series(
@@ -575,7 +576,8 @@ class BaseConnector(ABC):
             )
         else:
             raise ItemInLibraryException(
-                f"Model with name '{name}' " "already in 'models' library!"
+                f"Model with name '{name}' already in 'models' library! "
+                "Use overwrite=True to replace existing model."
             )
         self._clear_cache("_modelnames_cache")
         self._add_oseries_model_links(str(mldict["oseries"]["name"]), name)
@@ -1093,8 +1095,7 @@ class BaseConnector(ABC):
         """
         if prompt:
             ui = input(
-                f"Do you want to empty '{libname}'"
-                " library of all its contents? [y/N] "
+                f"Do you want to empty '{libname}' library of all its contents? [y/N] "
             )
             if ui.lower() != "y":
                 return
@@ -1115,7 +1116,7 @@ class BaseConnector(ABC):
             ):
                 self._del_item(libname, name)
             self._clear_cache(libname)
-            print(f"Emptied library {libname} in {self.name}: " f"{self.__class__}")
+            print(f"Emptied library {libname} in {self.name}: {self.__class__}")
 
     def _iter_series(self, libname: str, names: Optional[List[str]] = None):
         """Iterate over time series in library (internal method).
@@ -1365,10 +1366,36 @@ class BaseConnector(ABC):
 class ModelAccessor:
     """Object for managing access to stored models.
 
-    Provides dict-like access to models (i.e. PastaStore.models["model1"]), or allows
-    adding models to the PastaStore using dict-like assignment (i.e.
-    PastaStore.models["model1"] = ml), and it can serve as an iterator (i.e. [ml for ml
-    in pstore.models]).
+    The ModelAccessor object allows dictionary-like assignment and access to models.
+    In addition it provides some useful utilities for working with stored models
+    in the database.
+
+    Examples
+    --------
+    Get a model by name::
+
+    >>> model = pstore.models["my_model"]
+
+    Store a model in the database::
+
+    >>> pstore.models["my_model_v2"] = model
+
+    Get model metadata dataframe::
+
+    >>> pstore.models.metadata
+
+    Number of models::
+
+    >>> len(pstore.models)
+
+    Random model::
+
+    >>> model = pstore.models.random()
+
+    Iterate over stored models::
+
+    >>> for ml in pstore.models:
+    >>>     ml.solve()
     """
 
     def __init__(self, conn):
@@ -1382,8 +1409,11 @@ class ModelAccessor:
         self.conn = conn
 
     def __repr__(self):
-        """Representation of the object is a list of modelnames."""
-        return self.conn._modelnames_cache.__repr__()
+        """Representation contains the number of models and the list of model names."""
+        return (
+            f"<{self.__class__.__name__}> {len(self)} model(s): \n"
+            + self.conn._modelnames_cache.__repr__()
+        )
 
     def __getitem__(self, name: str):
         """Get model from store with model name as key.
@@ -1436,3 +1466,27 @@ class ModelAccessor:
         from random import choice
 
         return self.conn.get_models(choice(self.conn._modelnames_cache))
+
+    @property
+    def metadata(self):
+        """Dataframe with overview of models metadata."""
+        # NOTE: cannot be cached as this dataframe is not a property of the connector
+        # I'm not sure how to clear this cache when models are added/removed.
+        idx = pd.MultiIndex.from_tuples(
+            ((k, i) for k, v in self.conn.oseries_models.items() for i in v),
+            names=["oseries", "modelname"],
+        )
+        modeldf = pd.DataFrame(index=idx)
+        modeldf = modeldf.join(
+            self.conn.oseries, on=modeldf.index.get_level_values(0)
+        ).drop("key_0", axis=1)
+        modeldf["n_stressmodels"] = 0
+        for onam, mlnam in modeldf.index:
+            mldict = self.conn.get_models(mlnam, return_dict=True)
+            modeldf.loc[(onam, mlnam), "n_stressmodels"] = len(mldict["stressmodels"])
+            modeldf.loc[(onam, mlnam), "stressmodel_names"] = ",".join(
+                list(mldict["stressmodels"].keys())
+            )
+            for setting in mldict["settings"].keys():
+                modeldf.loc[(onam, mlnam), setting] = mldict["settings"][setting]
+        return modeldf

pastastore/connectors.py

@@ -370,8 +370,7 @@ class ConnectorUtil:
             raise TypeError("Expected pastas.Model or dict!")
         if name not in self.oseries.index:
             msg = (
-                f"Cannot add model because oseries '{name}' "
-                "is not contained in store."
+                f"Cannot add model because oseries '{name}' is not contained in store."
             )
             raise LookupError(msg)
         # expensive check
@@ -764,6 +763,7 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
         """
         try:
             import arcticdb
+
         except ModuleNotFoundError as e:
             print("Please install arcticdb with `pip install arcticdb`!")
             raise e
@@ -777,6 +777,9 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
         # for older versions of PastaStore, if oseries_models library is empty
         # populate oseries - models database
         self._update_all_oseries_model_links()
+        # write pstore file to store database info that can be used to load pstore
+        if "lmdb" in self.uri:
+            self.write_pstore_config_file()
 
     def _initialize(self, verbose: bool = True) -> None:
         """Initialize the libraries (internal method)."""
@@ -792,6 +795,29 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
                     )
             self.libs[libname] = self._get_library(libname)
 
+    def write_pstore_config_file(self, path: str = None) -> None:
+        """Write pstore configuration file to store database info."""
+        # NOTE: method is not private as theoretically an ArcticDB
+        # database could also be hosted in the cloud, in which case,
+        # writing this config in the folder holding the database
+        # is no longer possible. For those situations, the user can
+        # write this config file and specify the path it should be
+        # written to.
+        config = {
+            "connector_type": self.conn_type,
+            "name": self.name,
+            "uri": self.uri,
+        }
+        if path is None and "lmdb" in self.uri:
+            path = self.uri.split("://")[1]
+        elif path is None and "lmdb" not in self.uri:
+            raise ValueError("Please provide a path to write the pastastore file!")
+
+        with open(
+            os.path.join(path, f"{self.name}.pastastore"), "w", encoding="utf-8"
+        ) as f:
+            json.dump(config, f)
+
     def _library_name(self, libname: str) -> str:
         """Get full library name according to ArcticDB (internal method)."""
         return ".".join([self.name, libname])
@@ -1165,6 +1191,7 @@ class PasConnector(BaseConnector, ConnectorUtil):
             whether to print message when database is initialized, by default True
         """
         self.name = name
+        self.parentdir = path
         self.path = os.path.abspath(os.path.join(path, self.name))
         self.relpath = os.path.relpath(self.path)
         self._initialize(verbose=verbose)
@@ -1172,6 +1199,8 @@ class PasConnector(BaseConnector, ConnectorUtil):
         # for older versions of PastaStore, if oseries_models library is empty
         # populate oseries_models library
         self._update_all_oseries_model_links()
+        # write pstore file to store database info that can be used to load pstore
+        self._write_pstore_config_file()
 
     def _initialize(self, verbose: bool = True) -> None:
         """Initialize the libraries (internal method)."""
@@ -1189,6 +1218,18 @@ class PasConnector(BaseConnector, ConnectorUtil):
                     )
             setattr(self, f"lib_{val}", os.path.join(self.path, val))
 
+    def _write_pstore_config_file(self):
+        """Write pstore configuration file to store database info."""
+        config = {
+            "connector_type": self.conn_type,
+            "name": self.name,
+            "path": os.path.abspath(self.parentdir),
+        }
+        with open(
+            os.path.join(self.path, f"{self.name}.pastastore"), "w", encoding="utf-8"
+        ) as f:
+            json.dump(config, f)
+
     def _get_library(self, libname: str):
         """Get path to directory holding data.
 

pastastore/extensions/hpd.py

@@ -45,6 +45,13 @@ class HydroPandasExtension:
         """
         self._store = store
 
+    def __repr__(self):
+        """Return string representation of HydroPandasExtension."""
+        methods = "".join(
+            [f"\n - {meth}" for meth in dir(self) if not meth.startswith("_")]
+        )
+        return "HydroPandasExtension, available methods:" + methods
+
     def add_obscollection(
         self,
         libname: str,
@@ -259,7 +266,7 @@ class HydroPandasExtension:
         meteo_var: str = "RD",
         tmin: TimeType = None,
         tmax: TimeType = None,
-        unit_multiplier: float = 1e-3,
+        unit_multiplier: float = 1e3,
         fill_missing_obs: bool = True,
         normalize_datetime_index: bool = True,
         **kwargs,
@@ -298,7 +305,7 @@ class HydroPandasExtension:
         meteo_var: str = "EV24",
         tmin: TimeType = None,
         tmax: TimeType = None,
-        unit_multiplier: float = 1e-3,
+        unit_multiplier: float = 1e3,
         fill_missing_obs: bool = True,
         normalize_datetime_index: bool = True,
         **kwargs,
@@ -409,7 +416,7 @@ class HydroPandasExtension:
         meteo_var: str = "RD",
         tmin: Optional[TimeType] = None,
         tmax: Optional[TimeType] = None,
-        unit_multiplier: float = 1e-3,
+        unit_multiplier: float = 1e3,
         normalize_datetime_index: bool = True,
         fill_missing_obs: bool = True,
         **kwargs,
@@ -428,7 +435,7 @@ class HydroPandasExtension:
             end time
         unit_multiplier : float, optional
             multiply unit by this value before saving it in the store,
-            by default 1.0 (no conversion)
+            by default 1e3 (converting m to mm)
         fill_missing_obs : bool, optional
             if True, fill missing observations by getting observations from nearest
             station with data.
@@ -454,7 +461,7 @@ class HydroPandasExtension:
         meteo_var: str = "EV24",
         tmin: Optional[TimeType] = None,
         tmax: Optional[TimeType] = None,
-        unit_multiplier: float = 1e-3,
+        unit_multiplier: float = 1e3,
         normalize_datetime_index: bool = True,
         fill_missing_obs: bool = True,
         **kwargs,
@@ -474,7 +481,7 @@ class HydroPandasExtension:
             end time
         unit_multiplier : float, optional
             multiply unit by this value before saving it in the store,
-            by default 1.0 (no conversion)
+            by default 1e3 (converting m to mm)
         fill_missing_obs : bool, optional
             if True, fill missing observations by getting observations from nearest
             station with data.