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

pastastore/connectors.py

@@ -1,3 +1,5 @@
+"""Module containing classes for connecting to different data stores."""
+
 import json
 import os
 import warnings
@@ -16,11 +18,12 @@ warnings.showwarning = _custom_warning
 
 
 class ArcticConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
+    """ArcticConnector object that connects to a running MongoDB database via Arctic."""
+
     conn_type = "arctic"
 
     def __init__(self, name: str, connstr: str):
-        """Create an ArcticConnector object that connects to a running MongoDB
-        database via Arctic.
+        """Create an ArcticConnector object that connects to a MongoDB database.
 
         Parameters
         ----------
@@ -29,6 +32,12 @@ class ArcticConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         connstr : str
             connection string (e.g. 'mongodb://localhost:27017/')
         """
+        warnings.warn(
+            "ArcticConnector is deprecated. Please use a different "
+            "connector, e.g. `pst.ArcticDBConnector`.",
+            DeprecationWarning,
+            stacklevel=1,
+        )
         try:
             import arctic
         except ModuleNotFoundError as e:
@@ -52,8 +61,7 @@ class ArcticConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         self._update_all_oseries_model_links()
 
     def _initialize(self) -> None:
-        """Internal method to initalize the libraries."""
-
+        """Initialize the libraries (internal method)."""
         for libname in self._default_library_names:
             if self._library_name(libname) not in self.arc.list_libraries():
                 self.arc.initialize_library(self._library_name(libname))
@@ -66,7 +74,7 @@ class ArcticConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
             self.libs[libname] = self._get_library(libname)
 
     def _library_name(self, libname: str) -> str:
-        """Internal method to get full library name according to Arctic."""
+        """Get full library name according to Arctic (internal method)."""
         return ".".join([self.name, libname])
 
     def _get_library(self, libname: str):
@@ -94,7 +102,7 @@ class ArcticConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         metadata: Optional[Dict] = None,
         **_,
     ) -> None:
-        """Internal method to add item to library (time series or model).
+        """Add item to library (time series or model) (internal method).
 
         Parameters
         ----------
@@ -111,7 +119,7 @@ class ArcticConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         lib.write(name, item, metadata=metadata)
 
     def _get_item(self, libname: str, name: str) -> Union[FrameorSeriesUnion, Dict]:
-        """Internal method to retrieve item from library.
+        """Retrieve item from library (internal method).
 
         Parameters
         ----------
@@ -129,7 +137,7 @@ class ArcticConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         return lib.read(name).data
 
     def _del_item(self, libname: str, name: str) -> None:
-        """Internal method to delete items (series or models).
+        """Delete items (series or models) (internal method).
 
         Parameters
         ----------
@@ -142,7 +150,7 @@ class ArcticConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         lib.delete(name)
 
     def _get_metadata(self, libname: str, name: str) -> dict:
-        """Internal method to retrieve metadata for an item.
+        """Retrieve metadata for an item (internal method).
 
         Parameters
         ----------
@@ -199,6 +207,8 @@ class ArcticConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
 
 
 class ArcticDBConnector(BaseConnector, ConnectorUtil):
+    """ArcticDBConnector object using ArcticDB to store data."""
+
     conn_type = "arcticdb"
 
     def __init__(self, name: str, uri: str):
@@ -228,8 +238,7 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
         self._update_all_oseries_model_links()
 
     def _initialize(self) -> None:
-        """Internal method to initalize the libraries."""
-
+        """Initialize the libraries (internal method)."""
         for libname in self._default_library_names:
             if self._library_name(libname) not in self.arc.list_libraries():
                 self.arc.create_library(self._library_name(libname))
@@ -242,7 +251,7 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
             self.libs[libname] = self._get_library(libname)
 
     def _library_name(self, libname: str) -> str:
-        """Internal method to get full library name according to ArcticDB."""
+        """Get full library name according to ArcticDB (internal method)."""
         return ".".join([self.name, libname])
 
     def _get_library(self, libname: str):
@@ -270,7 +279,7 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
         metadata: Optional[Dict] = None,
         **_,
     ) -> None:
-        """Internal method to add item to library (time series or model).
+        """Add item to library (time series or model) (internal method).
 
         Parameters
         ----------
@@ -292,7 +301,7 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
             lib.write(name, item, metadata=metadata)
 
     def _get_item(self, libname: str, name: str) -> Union[FrameorSeriesUnion, Dict]:
-        """Internal method to retrieve item from library.
+        """Retrieve item from library (internal method).
 
         Parameters
         ----------
@@ -310,7 +319,7 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
         return lib.read(name).data
 
     def _del_item(self, libname: str, name: str) -> None:
-        """Internal method to delete items (series or models).
+        """Delete items (series or models) (internal method).
 
         Parameters
         ----------
@@ -323,7 +332,7 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
         lib.delete(name)
 
     def _get_metadata(self, libname: str, name: str) -> dict:
-        """Internal method to retrieve metadata for an item.
+        """Retrieve metadata for an item (internal method).
 
         Parameters
         ----------
@@ -380,6 +389,8 @@ class ArcticDBConnector(BaseConnector, ConnectorUtil):
 
 
 class PystoreConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
+    """PystoreConnector object using pystore as database backend."""
+
     conn_type = "pystore"
 
     def __init__(self, name: str, path: str):
@@ -392,6 +403,12 @@ class PystoreConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         path : str
             path to the pystore directory
         """
+        warnings.warn(
+            "PystoreConnector is deprecated. Please use a different "
+            "connector, e.g. `pst.PasConnector`.",
+            DeprecationWarning,
+            stacklevel=1,
+        )
         try:
             import pystore
         except ModuleNotFoundError as e:
@@ -412,7 +429,7 @@ class PystoreConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         self._update_all_oseries_model_links()
 
     def _initialize(self) -> None:
-        """Internal method to initalize the libraries (stores)."""
+        """Initialize the libraries (stores) (internal method)."""
         for libname in self._default_library_names:
             if libname in self.store.list_collections():
                 print(
@@ -447,7 +464,7 @@ class PystoreConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         metadata: Optional[Dict] = None,
         overwrite: bool = False,
     ) -> None:
-        """Internal method to add item to library (time series or model).
+        """Add item to library (time series or model) (internal method).
 
         Parameters
         ----------
@@ -489,7 +506,7 @@ class PystoreConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         lib.write(name, s, metadata=metadata, overwrite=overwrite)
 
     def _get_item(self, libname: str, name: str) -> Union[FrameorSeriesUnion, Dict]:
-        """Internal method to retrieve item from pystore library.
+        """Retrieve item from pystore library (internal method).
 
         Parameters
         ----------
@@ -522,7 +539,7 @@ class PystoreConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         return s
 
     def _del_item(self, libname: str, name: str) -> None:
-        """Internal method to delete data from the store.
+        """Delete data from the store (internal method).
 
         Parameters
         ----------
@@ -536,7 +553,7 @@ class PystoreConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
         self._clear_cache(libname)
 
     def _get_metadata(self, libname: str, name: str) -> dict:
-        """Internal method to read metadata from pystore.
+        """Read metadata from pystore (internal method).
 
         Parameters
         ----------
@@ -600,6 +617,8 @@ class PystoreConnector(BaseConnector, ConnectorUtil):  # pragma: no cover
 
 
 class DictConnector(BaseConnector, ConnectorUtil):
+    """DictConnector object that stores timeseries and models in dictionaries."""
+
     conn_type = "dict"
 
     def __init__(self, name: str = "pastas_db"):
@@ -643,7 +662,7 @@ class DictConnector(BaseConnector, ConnectorUtil):
         metadata: Optional[Dict] = None,
         **_,
     ) -> None:
-        """Internal method to add item (time series or models).
+        """Add item (time series or models) (internal method).
 
         Parameters
         ----------
@@ -663,7 +682,7 @@ class DictConnector(BaseConnector, ConnectorUtil):
             lib[name] = (metadata, item)
 
     def _get_item(self, libname: str, name: str) -> Union[FrameorSeriesUnion, Dict]:
-        """Internal method to retrieve item from pystore library.
+        """Retrieve item from database (internal method).
 
         Parameters
         ----------
@@ -685,7 +704,7 @@ class DictConnector(BaseConnector, ConnectorUtil):
         return item
 
     def _del_item(self, libname: str, name: str) -> None:
-        """Internal method to delete items (series or models).
+        """Delete items (series or models) (internal method).
 
         Parameters
         ----------
@@ -698,7 +717,7 @@ class DictConnector(BaseConnector, ConnectorUtil):
         _ = lib.pop(name)
 
     def _get_metadata(self, libname: str, name: str) -> dict:
-        """Internal method to read metadata.
+        """Read metadata (internal method).
 
         Parameters
         ----------
@@ -742,6 +761,8 @@ class DictConnector(BaseConnector, ConnectorUtil):
 
 
 class PasConnector(BaseConnector, ConnectorUtil):
+    """PasConnector object that stores time series and models as JSON files on disk."""
+
     conn_type = "pas"
 
     def __init__(self, name: str, path: str):
@@ -767,7 +788,7 @@ class PasConnector(BaseConnector, ConnectorUtil):
         self._update_all_oseries_model_links()
 
     def _initialize(self) -> None:
-        """Internal method to initialize the libraries."""
+        """Initialize the libraries (internal method)."""
         for val in self._default_library_names:
             libdir = os.path.join(self.path, val)
             if not os.path.exists(libdir):
@@ -803,7 +824,7 @@ class PasConnector(BaseConnector, ConnectorUtil):
         metadata: Optional[Dict] = None,
         **_,
     ) -> None:
-        """Internal method to add item (time series or models).
+        """Add item (time series or models) (internal method).
 
         Parameters
         ----------
@@ -845,7 +866,7 @@ class PasConnector(BaseConnector, ConnectorUtil):
                 fm.write(jsondict)
 
     def _get_item(self, libname: str, name: str) -> Union[FrameorSeriesUnion, Dict]:
-        """Internal method to retrieve item.
+        """Retrieve item (internal method).
 
         Parameters
         ----------
@@ -878,7 +899,7 @@ class PasConnector(BaseConnector, ConnectorUtil):
         return item
 
     def _del_item(self, libname: str, name: str) -> None:
-        """Internal method to delete items (series or models).
+        """Delete items (series or models) (internal method).
 
         Parameters
         ----------
@@ -898,7 +919,7 @@ class PasConnector(BaseConnector, ConnectorUtil):
                 pass
 
     def _get_metadata(self, libname: str, name: str) -> dict:
-        """Internal method to read metadata.
+        """Read metadata (internal method).
 
         Parameters
         ----------

pastastore/datasets.py

@@ -1,3 +1,5 @@
+"""Module containing example dataset."""
+
 import os
 
 import pandas as pd
@@ -13,7 +15,7 @@ from pastastore.base import BaseConnector
 
 
 def example_pastastore(conn="DictConnector"):
-    """Example dataset loaded into PastaStore.
+    """Get example PastaStore.
 
     Parameters
     ----------
@@ -27,7 +29,6 @@ def example_pastastore(conn="DictConnector"):
     pstore : pastastore.PastaStore
         PastaStore containing example dataset
     """
-
     # check it test dataset is available
     datadir = os.path.join(os.path.dirname(__file__), "../tests/data")
     if not os.path.exists(datadir):

pastastore/plotting.py

@@ -1,4 +1,4 @@
-"""This module contains all the plotting methods for PastaStore.
+"""Module containing all the plotting methods for PastaStore.
 
 Pastastore comes with a number helpful plotting methods to quickly
 visualize time series or the locations of the time series contained in the
@@ -55,7 +55,7 @@ class Plots:
         legend_kwargs=None,
         **kwargs,
     ):
-        """Internal method to plot time series from pastastore.
+        """Plot time series from pastastore (internal method).
 
         Parameters
         ----------
@@ -507,7 +507,6 @@ class Plots:
         ax : matplotlib Axes
             The axes in which the cumulative histogram is plotted
         """
-
         statsdf = self.pstore.get_statistics(
             [statistic], modelnames=modelnames, progressbar=False
         )
@@ -563,6 +562,23 @@ class Plots:
         return ax
 
     def compare_models(self, modelnames, ax=None, **kwargs):
+        """Compare multiple models and plot the results.
+
+        Parameters
+        ----------
+        modelnames : list
+            A list of model names to compare.
+        ax : matplotlib.axes.Axes, optional
+            The axes on which to plot the comparison. If not provided, a new figure
+            and axes will be created.
+        **kwargs : dict
+            Additional keyword arguments to pass to the plot function.
+
+        Returns
+        -------
+        cm : pastastore.CompareModels
+            The CompareModels object containing the comparison results.
+        """
         models = self.pstore.get_models(modelnames)
         names = []
         onames = [iml.oseries.name for iml in models]
@@ -644,7 +660,7 @@ class Maps:
         ax: matplotlib.Axes
             axes object
 
-        See also
+        See Also
         --------
         self.add_background_map
         """
@@ -722,11 +738,10 @@ class Maps:
         ax: matplotlib.Axes
             axes object
 
-        See also
+        See Also
         --------
         self.add_background_map
         """
-
         names = self.pstore.conn._parse_names(names, "oseries")
         if extent is not None:
             names = self.pstore.within(extent, names=names)
@@ -774,11 +789,10 @@ class Maps:
         ax: matplotlib.Axes
             axes object
 
-        See also
+        See Also
         --------
         self.add_background_map
         """
-
         model_oseries = [
             self.pstore.get_models(m, return_dict=True)["oseries"]["name"]
             for m in self.pstore.model_names
@@ -849,7 +863,7 @@ class Maps:
         ax: matplotlib.Axes
             axes object
 
-        See also
+        See Also
         --------
         self.add_background_map
         """
@@ -898,7 +912,7 @@ class Maps:
         figsize=(10, 8),
         **kwargs,
     ):
-        """Internal method for plotting dataframe with point locations.
+        """Plot dataframe with point locations (internal method).
 
         Can be called directly for more control over plot characteristics.
 
@@ -932,7 +946,6 @@ class Maps:
         sc : scatter handle
             scatter plot handle, returned if ax is not None
         """
-
         if ax is None:
             return_scatter = False
             fig, ax = plt.subplots(figsize=figsize)
@@ -1016,7 +1029,7 @@ class Maps:
         ax: axes object
             axis handle of the resulting figure
 
-        See also
+        See Also
         --------
         self.add_background_map
         """
@@ -1102,7 +1115,7 @@ class Maps:
         uniques = stresses.loc[:, ["stressmodel", "color"]].drop_duplicates(
             keep="first"
         )
-        for name, row in uniques.iterrows():
+        for _, row in uniques.iterrows():
             (h,) = ax.plot(
                 [],
                 [],
@@ -1201,7 +1214,7 @@ class Maps:
         ax: axes object
             axis handle of the resulting figure
 
-        See also
+        See Also
         --------
         self.add_background_map
         """