gensor 0.1.7__tar.gz → 0.2.2__tar.gz

{gensor-0.1.7 → gensor-0.2.2}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024, Mateusz Zawadzki
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024, Mateusz Zawadzki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{gensor-0.1.7 → gensor-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: gensor
-Version: 0.1.7
+Version: 0.2.2
 Summary: Library for handling groundwater sensor data.
 Home-page: https://github.com/zawadzkim/gensor
 Author: Mateusz Zawadzki

gensor-0.2.2/gensor/__init__.py

@@ -0,0 +1,29 @@
+import logging
+
+from .core.dataset import Dataset
+from .core.timeseries import Timeseries
+from .io.read import read_from_csv, read_from_sql
+from .log import set_log_level
+from .processing.compensation import compensate
+
+__all__ = [
+    # basic data types
+    "Dataset",
+    "Timeseries",
+    "compensate",
+    # getters
+    "read_from_csv",
+    "read_from_sql",
+    "set_log_level",
+]
+
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+if not logger.hasHandlers():
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.INFO)
+    formatter = logging.Formatter("%(levelname)s: %(message)s")
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)

{gensor-0.1.7 → gensor-0.2.2}/gensor/analysis/outliers.py

@@ -1,173 +1,173 @@
-from collections.abc import Callable
-from typing import Any, Literal
-
-import numpy as np
-from pandas import Series
-from sklearn.ensemble import IsolationForest
-from sklearn.neighbors import LocalOutlierFactor
-
-
-class OutlierDetection:
-    """Detecting outliers in groundwater timeseries data.
-
-    Each method in this class returns a pandas.Series containing predicted outliers in
-    the dataset.
-
-    Methods:
-        iqr: Use interquartile range (IQR).
-        zscore: Use the z-score method.
-        isolation_forest: Using the isolation forest algorithm.
-        lof: Using the local outlier factor (LOF) method.
-    """
-
-    def __init__(
-        self,
-        data: Series,
-        method: Literal["iqr", "zscore", "isolation_forest", "lof"],
-        rolling: bool,
-        window: int,
-        **kwargs: Any,
-    ) -> None:
-        """Find outliers in a time series using the specified method, with an option for rolling window."""
-
-        FUNCS: dict[str, Callable] = {
-            "iqr": self.iqr,
-            "zscore": self.zscore,
-            "isolation_forest": self.isolation_forest,
-            "lof": self.lof,
-        }
-
-        method_func = FUNCS[method]
-
-        if method in ["iqr", "zscore"]:
-            # For 'iqr' and 'zscore' methods
-            y = (
-                kwargs.get("k", 1.5)
-                if method == "iqr"
-                else kwargs.get("threshold", 3.0)
-            )
-            if rolling:
-                roll = data.rolling(window=window)
-                mask = roll.apply(lambda x: method_func(x, y, rolling=True), raw=True)
-            else:
-                mask = method_func(data.to_numpy(), y, rolling=False)
-
-            bool_mask = mask.astype(bool)
-            bool_mask_series = Series(bool_mask, index=data.index)
-            self.outliers = data[bool_mask_series]
-
-        else:
-            # For 'isolation_forest' and 'lof' methods
-            self.outliers = method_func(data, **kwargs)
-
-    @staticmethod
-    def iqr(data: np.ndarray, k: float, rolling: bool) -> np.ndarray:
-        """Use interquartile range (IQR).
-
-        Parameters:
-            data (pandas.Series): The time series data.
-
-        Keyword Args:
-            k (float): The multiplier for the IQR to define the range. Defaults to 1.5.
-
-        Returns:
-            np.ndarray: Binary mask representing the outliers as 1.
-        """
-
-        Q1 = np.percentile(data, 0.25)
-        Q3 = np.percentile(data, 0.75)
-        IQR = Q3 - Q1
-
-        lower_bound = Q1 - k * IQR
-        upper_bound = Q3 + k * IQR
-
-        if rolling:
-            return (
-                np.array([1])
-                if (data[-1] < lower_bound or data[-1] > upper_bound)
-                else np.array([0])
-            )
-
-        return np.where((data < lower_bound) | (data > upper_bound), 1, 0)
-
-    @staticmethod
-    def zscore(data: np.ndarray, threshold: float, rolling: bool) -> np.ndarray:
-        """Use the z-score method.
-
-        Parameters:
-            data (pandas.Series): The time series data.
-
-        Keyword Args:
-            threshold (float): The threshold for the z-score method. Defaults to 3.0.
-
-        Returns:
-            pandas.Series: Binary mask representing outliers.
-        """
-
-        mean = np.mean(data)
-        std_dev = np.std(data)
-
-        z_scores = np.abs((data - mean) / std_dev)
-
-        if rolling:
-            return np.array([1]) if z_scores[-1] > threshold else np.array([0])
-        return np.where(z_scores > threshold, 1, 0)
-
-    def isolation_forest(self, data: Series, **kwargs: Any) -> Series:
-        """Using the isolation forest algorithm.
-
-        Parameters:
-            data (pandas.Series): The time series data.
-
-        Keyword Args:
-            n_estimators (int): The number of base estimators in the ensemble. Defaults to 100.
-            max_samples (int | 'auto' | float): The number of samples to draw from X to train each base estimator. Defaults to 'auto'.
-            contamination (float): The proportion of outliers in the data. Defaults to 0.01.
-            max_features (int | float): The number of features to draw from X to train each base estimator. Defaults to 1.0.
-            bootstrap (bool): Whether to use bootstrapping when sampling the data. Defaults to False.
-            n_jobs (int): The number of jobs to run in parallel. Defaults to 1.
-            random_state (int | RandomState | None): The random state to use. Defaults to None.
-            verbose (int): The verbosity level. Defaults to 0.
-            warm_start (bool): Whether to reuse the solution of the previous call to fit and add more estimators to the ensemble. Defaults to False.
-
-        Note:
-            For details on kwargs see: sklearn.ensemble.IsolationForest.
-        """
-
-        X = data.to_numpy().reshape(-1, 1)
-
-        clf = IsolationForest(**kwargs)
-        clf.fit(X)
-
-        is_outlier = clf.predict(X)
-        outliers: Series = data[is_outlier == -1]
-
-        return outliers
-
-    def lof(self, data: Series, **kwargs: Any) -> Series:
-        """Using the local outlier factor (LOF) method.
-
-        Parameters:
-            data (pandas.Series): The time series data.
-
-        Keyword Args:
-            n_neighbors (int): The number of neighbors to consider for each sample. Defaults to 20.
-            algorithm (str): The algorithm to use. Either 'auto', 'ball_tree', 'kd_tree' or 'brute'. Defaults to 'auto'.
-            leaf_size (int): The leaf size of the tree. Defaults to 30.
-            metric (str): The distance metric to use. Defaults to 'minkowski'.
-            p (int): The power parameter for the Minkowski metric. Defaults to 2.
-            contamination (float): The proportion of outliers in the data. Defaults to 0.01.
-            novelty (bool): Whether to consider the samples as normal or outliers. Defaults to False.
-            n_jobs (int): The number of jobs to run in parallel. Defaults to 1.
-        Note:
-            For details on kwargs see: sklearn.neighbors.LocalOutlierFactor.
-        """
-
-        X = data.to_numpy().reshape(-1, 1)
-
-        clf = LocalOutlierFactor(**kwargs)
-
-        is_outlier = clf.fit_predict(X)
-        outliers: Series = data[is_outlier == -1]
-
-        return outliers
+from collections.abc import Callable
+from typing import Any, Literal
+
+import numpy as np
+from pandas import Series
+from sklearn.ensemble import IsolationForest
+from sklearn.neighbors import LocalOutlierFactor
+
+
+class OutlierDetection:
+    """Detecting outliers in groundwater timeseries data.
+
+    Each method in this class returns a pandas.Series containing predicted outliers in
+    the dataset.
+
+    Methods:
+        iqr: Use interquartile range (IQR).
+        zscore: Use the z-score method.
+        isolation_forest: Using the isolation forest algorithm.
+        lof: Using the local outlier factor (LOF) method.
+    """
+
+    def __init__(
+        self,
+        data: Series,
+        method: Literal["iqr", "zscore", "isolation_forest", "lof"],
+        rolling: bool,
+        window: int,
+        **kwargs: Any,
+    ) -> None:
+        """Find outliers in a time series using the specified method, with an option for rolling window."""
+
+        FUNCS: dict[str, Callable] = {
+            "iqr": self.iqr,
+            "zscore": self.zscore,
+            "isolation_forest": self.isolation_forest,
+            "lof": self.lof,
+        }
+
+        method_func = FUNCS[method]
+
+        if method in ["iqr", "zscore"]:
+            # For 'iqr' and 'zscore' methods
+            y = (
+                kwargs.get("k", 1.5)
+                if method == "iqr"
+                else kwargs.get("threshold", 3.0)
+            )
+            if rolling:
+                roll = data.rolling(window=window)
+                mask = roll.apply(lambda x: method_func(x, y, rolling=True), raw=True)
+            else:
+                mask = method_func(data.to_numpy(), y, rolling=False)
+
+            bool_mask = mask.astype(bool)
+            bool_mask_series = Series(bool_mask, index=data.index)
+            self.outliers = data[bool_mask_series]
+
+        else:
+            # For 'isolation_forest' and 'lof' methods
+            self.outliers = method_func(data, **kwargs)
+
+    @staticmethod
+    def iqr(data: np.ndarray, k: float, rolling: bool) -> np.ndarray:
+        """Use interquartile range (IQR).
+
+        Parameters:
+            data (pandas.Series): The time series data.
+
+        Keyword Args:
+            k (float): The multiplier for the IQR to define the range. Defaults to 1.5.
+
+        Returns:
+            np.ndarray: Binary mask representing the outliers as 1.
+        """
+
+        Q1 = np.percentile(data, 0.25)
+        Q3 = np.percentile(data, 0.75)
+        IQR = Q3 - Q1
+
+        lower_bound = Q1 - k * IQR
+        upper_bound = Q3 + k * IQR
+
+        if rolling:
+            return (
+                np.array([1])
+                if (data[-1] < lower_bound or data[-1] > upper_bound)
+                else np.array([0])
+            )
+
+        return np.where((data < lower_bound) | (data > upper_bound), 1, 0)
+
+    @staticmethod
+    def zscore(data: np.ndarray, threshold: float, rolling: bool) -> np.ndarray:
+        """Use the z-score method.
+
+        Parameters:
+            data (pandas.Series): The time series data.
+
+        Keyword Args:
+            threshold (float): The threshold for the z-score method. Defaults to 3.0.
+
+        Returns:
+            pandas.Series: Binary mask representing outliers.
+        """
+
+        mean = np.mean(data)
+        std_dev = np.std(data)
+
+        z_scores = np.abs((data - mean) / std_dev)
+
+        if rolling:
+            return np.array([1]) if z_scores[-1] > threshold else np.array([0])
+        return np.where(z_scores > threshold, 1, 0)
+
+    def isolation_forest(self, data: Series, **kwargs: Any) -> Series:
+        """Using the isolation forest algorithm.
+
+        Parameters:
+            data (pandas.Series): The time series data.
+
+        Keyword Args:
+            n_estimators (int): The number of base estimators in the ensemble. Defaults to 100.
+            max_samples (int | 'auto' | float): The number of samples to draw from X to train each base estimator. Defaults to 'auto'.
+            contamination (float): The proportion of outliers in the data. Defaults to 0.01.
+            max_features (int | float): The number of features to draw from X to train each base estimator. Defaults to 1.0.
+            bootstrap (bool): Whether to use bootstrapping when sampling the data. Defaults to False.
+            n_jobs (int): The number of jobs to run in parallel. Defaults to 1.
+            random_state (int | RandomState | None): The random state to use. Defaults to None.
+            verbose (int): The verbosity level. Defaults to 0.
+            warm_start (bool): Whether to reuse the solution of the previous call to fit and add more estimators to the ensemble. Defaults to False.
+
+        Note:
+            For details on kwargs see: sklearn.ensemble.IsolationForest.
+        """
+
+        X = data.to_numpy().reshape(-1, 1)
+
+        clf = IsolationForest(**kwargs)
+        clf.fit(X)
+
+        is_outlier = clf.predict(X)
+        outliers: Series = data[is_outlier == -1]
+
+        return outliers
+
+    def lof(self, data: Series, **kwargs: Any) -> Series:
+        """Using the local outlier factor (LOF) method.
+
+        Parameters:
+            data (pandas.Series): The time series data.
+
+        Keyword Args:
+            n_neighbors (int): The number of neighbors to consider for each sample. Defaults to 20.
+            algorithm (str): The algorithm to use. Either 'auto', 'ball_tree', 'kd_tree' or 'brute'. Defaults to 'auto'.
+            leaf_size (int): The leaf size of the tree. Defaults to 30.
+            metric (str): The distance metric to use. Defaults to 'minkowski'.
+            p (int): The power parameter for the Minkowski metric. Defaults to 2.
+            contamination (float): The proportion of outliers in the data. Defaults to 0.01.
+            novelty (bool): Whether to consider the samples as normal or outliers. Defaults to False.
+            n_jobs (int): The number of jobs to run in parallel. Defaults to 1.
+        Note:
+            For details on kwargs see: sklearn.neighbors.LocalOutlierFactor.
+        """
+
+        X = data.to_numpy().reshape(-1, 1)
+
+        clf = LocalOutlierFactor(**kwargs)
+
+        is_outlier = clf.fit_predict(X)
+        outliers: Series = data[is_outlier == -1]
+
+        return outliers

{gensor-0.1.7 → gensor-0.2.2}/gensor/analysis/stats.py

@@ -1,28 +1,28 @@
-"""Module to compute timeseries statistics, similar to pastas.stats.signatures module
-and following Heudorfer et al. 2019
-
-To be implemented:
-
-- Structure
- * Flashiness
-- Distribution
- * Modality
- * Density
-- Shape
- * Scale
- * Slope
-"""
-
-import numpy as np
-
-from gensor.core.timeseries import Timeseries
-
-
-def trend(ts: Timeseries) -> tuple:
-    time_numeric = np.arange(len(ts.timeseries))
-
-    # Perform linear regression using numpy's polyfit
-    # This returns the slope and intercept of the best fit line
-    slope, intercept = np.polyfit(time_numeric, ts.timeseries, 1)
-
-    return slope, intercept
+"""Module to compute timeseries statistics, similar to pastas.stats.signatures module
+and following Heudorfer et al. 2019
+
+To be implemented:
+
+- Structure
+ * Flashiness
+- Distribution
+ * Modality
+ * Density
+- Shape
+ * Scale
+ * Slope
+"""
+
+import numpy as np
+
+from gensor.core.timeseries import Timeseries
+
+
+def trend(ts: Timeseries) -> tuple:
+    time_numeric = np.arange(len(ts.timeseries))
+
+    # Perform linear regression using numpy's polyfit
+    # This returns the slope and intercept of the best fit line
+    slope, intercept = np.polyfit(time_numeric, ts.timeseries, 1)
+
+    return slope, intercept

{gensor-0.1.7 → gensor-0.2.2}/gensor/config.py

@@ -1,17 +1,17 @@
-"""
-!!! warning
-
-    Whenever Timeseries objects are created via read_from_csv and use a parser (e.g.,
-    'vanessen'), the timestamps are localized and converted to UTC. Therefore, if the
-    user creates his own timeseries outside the read_from_csv, they should ensure that
-    the timestamps are in UTC format.
-"""
-
-VARIABLE_TYPES_AND_UNITS = {
-    "temperature": ["degc"],
-    "pressure": ["cmh2o", "mmh2o"],
-    "conductivity": ["ms/cm"],
-    "flux": ["m/s"],
-    "head": ["m asl"],
-    "depth": ["m"],
-}
+"""
+!!! warning
+
+    Whenever Timeseries objects are created via read_from_csv and use a parser (e.g.,
+    'vanessen'), the timestamps are localized and converted to UTC. Therefore, if the
+    user creates his own timeseries outside the read_from_csv, they should ensure that
+    the timestamps are in UTC format.
+"""
+
+VARIABLE_TYPES_AND_UNITS = {
+    "temperature": ["degc"],
+    "pressure": ["cmh2o", "mmh2o"],
+    "conductivity": ["ms/cm"],
+    "flux": ["m/s"],
+    "head": ["m asl"],
+    "depth": ["m"],
+}