gensor 0.1.2__tar.gz → 0.1.3__tar.gz

{gensor-0.1.2 → gensor-0.1.3}/PKG-INFO

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

gensor-0.1.2/gensor/core/timeseries.py → gensor-0.1.3/gensor/core/base.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, Literal
+from typing import Any, Literal, TypeVar
 
 import pandas as pd
 import pandera as pa
@@ -15,6 +15,8 @@ from gensor.db import DatabaseConnection
 from gensor.exceptions import TimeseriesUnequal
 from gensor.processing.transform import Transformation
 
+T = TypeVar("T", bound="BaseTimeseries")
+
 ts_schema = pa.SeriesSchema(
     float,
     index=pa.Index(pd.DatetimeTZDtype(tz="UTC"), coerce=False),
@@ -22,18 +24,11 @@ ts_schema = pa.SeriesSchema(
 )
 
 
-class Timeseries(pyd.BaseModel):
-    """Timeseries from a sensor including measurement metadata.
-
-    This is class for any sensor timeseries. The basic required attributes are
-    just the ts, variable and unit. SensorInfo object is created from the
-    relevant kwargs if they are passed.
+class BaseTimeseries(pyd.BaseModel):
+    """Generic base class for timeseries with metadata.
 
-    Timeseries represents a series of measurements of a single variable, from a
-    single sensor with unique timestamps.
-
-    TODO: Perhaps it would be cool to implement kind of a tracking of which
-    analyses were performed on the timeseries?
+    Timeseries is a series of measurements of a single variable, in the same unit, from a
+    single location with unique timestamps.
 
     Attributes:
         ts (pd.Series): The timeseries data.
@@ -41,9 +36,8 @@ class Timeseries(pyd.BaseModel):
             The type of the measurement.
         unit (Literal['degC', 'mmH2O', 'mS/cm', 'm/s']): The unit of
             the measurement.
-        sensor (SensorInfo): The serial number of the sensor.
-        analysis (Analysis): An object containing details of analysis done
-            on the timeseries.
+        outliers (pd.Series): Measurements marked as outliers.
+        transformation (Any): Metadata of transformation the timeseries undergone.
 
     Methods:
         validate_ts: if the pd.Series is not exactly what is required, coerce.
@@ -59,8 +53,6 @@ class Timeseries(pyd.BaseModel):
     ]
     unit: Literal["degc", "cmh2o", "ms/cm", "m/s", "m asl", "m"]
     location: str | None = None
-    sensor: str | None = None
-    sensor_alt: float | None = None
     outliers: pd.Series | None = pyd.Field(default=None, repr=False)
     transformation: Any = pyd.Field(default=None, repr=False)
 
@@ -76,15 +68,13 @@ class Timeseries(pyd.BaseModel):
 
     def __eq__(self, other: object) -> bool:
         """Check equality based on location, sensor, variable, unit and sensor_alt."""
-        if not isinstance(other, Timeseries):
+        if not isinstance(other, BaseTimeseries):
             return NotImplemented
 
         return (
             self.variable == other.variable
             and self.unit == other.unit
             and self.location == other.location
-            and self.sensor == other.sensor
-            and self.sensor_alt == other.sensor_alt
         )
 
     def __getattr__(self, attr: Any) -> Any:
@@ -126,9 +116,9 @@ class Timeseries(pyd.BaseModel):
             return ts_schema.validate(v)
         return v
 
-    def concatenate(self, other: Timeseries) -> Timeseries:
+    def concatenate(self: T, other: T) -> T:
         """Concatenate two Timeseries objects if they are considered equal."""
-        if not isinstance(other, Timeseries):
+        if not isinstance(other, type(self)):
             return NotImplemented
 
         if self == other:
@@ -140,11 +130,11 @@ class Timeseries(pyd.BaseModel):
             raise TimeseriesUnequal()
 
     def resample(
-        self,
+        self: T,
         freq: Any,
         agg_func: Any = pd.Series.mean,
         **resample_kwargs: Any,
-    ) -> Timeseries:
+    ) -> T:
         """Resample the timeseries to a new frequency with a specified
         aggregation function.
 
@@ -165,7 +155,7 @@ class Timeseries(pyd.BaseModel):
         return self.model_copy(update={"ts": resampled_ts}, deep=True)
 
     def transform(
-        self,
+        self: T,
         method: Literal[
             "difference",
             "log",
@@ -177,7 +167,7 @@ class Timeseries(pyd.BaseModel):
             "maxabs_scaler",
         ],
         **transformer_kwargs: Any,
-    ) -> Timeseries:
+    ) -> T:
         """Transforms the timeseries using the specified method.
 
         Parameters:
@@ -200,13 +190,13 @@ class Timeseries(pyd.BaseModel):
         )
 
     def detect_outliers(
-        self,
+        self: T,
         method: Literal["iqr", "zscore", "isolation_forest", "lof"],
         rolling: bool = False,
         window: int = 6,
         remove: bool = True,
         **kwargs: Any,
-    ) -> Timeseries:
+    ) -> T:
         """Detects outliers in the timeseries using the specified method.
 
         Parameters:
@@ -230,8 +220,8 @@ class Timeseries(pyd.BaseModel):
             return self
 
     def mask_with(
-        self, other: Timeseries | pd.Series, mode: Literal["keep", "remove"] = "remove"
-    ) -> Timeseries:
+        self: T, other: T | pd.Series, mode: Literal["keep", "remove"] = "remove"
+    ) -> T:
         """
         Removes records not present in 'other' by index.
 
@@ -246,7 +236,7 @@ class Timeseries(pyd.BaseModel):
         """
         if isinstance(other, pd.Series):
             mask = other
-        elif isinstance(other, Timeseries):
+        elif isinstance(other, BaseTimeseries):
             mask = other.ts
 
         if mode == "keep":
@@ -259,7 +249,7 @@ class Timeseries(pyd.BaseModel):
 
         return self.model_copy(update={"ts": masked_data}, deep=True)
 
-    def to_sql(self, db: DatabaseConnection) -> str:
+    def to_sql(self: T, db: DatabaseConnection) -> str:
         """Converts the timeseries to a list of dictionaries and uploads it to the database.
 
         The Timeseries data is uploaded to the SQL database by using the pandas
@@ -276,7 +266,9 @@ class Timeseries(pyd.BaseModel):
         timestamp_start_fmt = self.start.strftime("%Y%m%d%H%M%S")
 
         # Construct the schema name using the location, sensor, variable, unit, and timestamp
-        schema_name = f"{self.location}_{self.sensor}_{self.variable}_{self.unit}_{timestamp_start_fmt}".lower()
+        schema_name = (
+            f"{self.location}_{self.variable}_{self.unit}_{timestamp_start_fmt}".lower()
+        )
 
         # Ensure the index is a pandas DatetimeIndex
         if isinstance(self.ts.index, pd.DatetimeIndex):
@@ -311,11 +303,8 @@ class Timeseries(pyd.BaseModel):
                 metadata_stmt = sqlite_insert(metadata_schema).values(
                     table_name=schema_name,
                     location=self.location,
-                    sensor=self.sensor,
                     variable=self.variable,
                     unit=self.unit,
-                    logger_alt=self.sensor_alt,
-                    location_alt=self.sensor_alt,
                     timestamp_start=timestamp_start_fmt,
                     timestamp_end=self.end.strftime("%Y%m%d%H%M%S"),
                 )
@@ -334,7 +323,7 @@ class Timeseries(pyd.BaseModel):
         return f"{schema_name} table and metadata updated."
 
     def plot(
-        self, include_outliers: bool = False, ax: Any = None, **plot_kwargs: Any
+        self: T, include_outliers: bool = False, ax: Any = None, **plot_kwargs: Any
     ) -> tuple:
         """Plots the timeseries data.
 
@@ -356,7 +345,7 @@ class Timeseries(pyd.BaseModel):
         ax.plot(
             self.ts.index,
             self.ts,
-            label=f"{self.location} ({self.sensor})",
+            label=f"{self.location}",
             **plot_kwargs,
         )
 

gensor-0.1.3/gensor/core/timeseries.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+import pandera as pa
+import pydantic as pyd
+from matplotlib import pyplot as plt
+from sqlalchemy import Table
+from sqlalchemy.dialects.sqlite import insert as sqlite_insert
+
+from gensor.core.base import BaseTimeseries
+from gensor.db import DatabaseConnection
+
+ts_schema = pa.SeriesSchema(
+    float,
+    index=pa.Index(pd.DatetimeTZDtype(tz="UTC"), coerce=False),
+    coerce=True,
+)
+
+
+class Timeseries(BaseTimeseries):
+    """Timeseries for groundwater sensor data
+
+    Attributes:
+        ts (pd.Series): The timeseries data.
+        variable (Literal['temperature', 'pressure', 'conductivity', 'flux']):
+            The type of the measurement.
+        unit (Literal['degC', 'mmH2O', 'mS/cm', 'm/s']): The unit of
+            the measurement.
+        sensor (SensorInfo): The serial number of the sensor.
+
+    Methods:
+        validate_ts: if the pd.Series is not exactly what is required, coerce.
+    """
+
+    model_config = pyd.ConfigDict(
+        arbitrary_types_allowed=True, validate_assignment=True
+    )
+
+    sensor: str | None = None
+    sensor_alt: float | None = None
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality based on location, sensor, variable, unit and sensor_alt."""
+        if not isinstance(other, Timeseries):
+            return NotImplemented
+
+        return (
+            self.variable == other.variable
+            and self.unit == other.unit
+            and self.location == other.location
+            and self.sensor == other.sensor
+            and self.sensor_alt == other.sensor_alt
+        )
+
+    def to_sql(self, db: DatabaseConnection) -> str:
+        """Converts the timeseries to a list of dictionaries and uploads it to the database.
+
+        The Timeseries data is uploaded to the SQL database by using the pandas
+        `to_sql` method. Additionally, metadata about the timeseries is stored in the
+        'timeseries_metadata' table.
+
+        Args:
+            db (DatabaseConnection): The database connection object.
+
+        Returns:
+            str: A message indicating the number of rows inserted into the database.
+        """
+        # Format the start timestamp as 'YYYYMMDDHHMMSS'
+        timestamp_start_fmt = self.start.strftime("%Y%m%d%H%M%S")
+
+        # Construct the schema name using the location, sensor, variable, unit, and timestamp
+        schema_name = f"{self.location}_{self.sensor}_{self.variable}_{self.unit}_{timestamp_start_fmt}".lower()
+
+        # Ensure the index is a pandas DatetimeIndex
+        if isinstance(self.ts.index, pd.DatetimeIndex):
+            utc_index = (
+                self.ts.index.tz_convert("UTC")
+                if self.ts.index.tz is not None
+                else self.ts.index
+            )
+        else:
+            message = "The index is not a DatetimeIndex and cannot be converted to UTC."
+            raise TypeError(message)
+
+        # Prepare the timeseries data as records for insertion
+        series_as_records = list(
+            zip(utc_index.strftime("%Y-%m-%dT%H:%M:%S%z"), self.ts, strict=False)
+        )
+
+        with db as con:
+            # Create the timeseries table if it doesn't exist
+            schema = db.create_table(schema_name, self.variable)
+
+            # Ensure that the timeseries_metadata table exists
+            metadata_schema = db.metadata.tables["__timeseries_metadata__"]
+
+            if isinstance(schema, Table):
+                # Insert the timeseries data
+                stmt = sqlite_insert(schema).values(series_as_records)
+                stmt = stmt.on_conflict_do_nothing(index_elements=["timestamp"])
+                con.execute(stmt)
+                con.commit()
+
+                metadata_stmt = sqlite_insert(metadata_schema).values(
+                    table_name=schema_name,
+                    location=self.location,
+                    sensor=self.sensor,
+                    variable=self.variable,
+                    unit=self.unit,
+                    logger_alt=self.sensor_alt,
+                    location_alt=self.sensor_alt,
+                    timestamp_start=timestamp_start_fmt,
+                    timestamp_end=self.end.strftime("%Y%m%d%H%M%S"),
+                )
+
+                metadata_stmt = metadata_stmt.on_conflict_do_update(
+                    index_elements=["table_name"],
+                    set_={
+                        "timestamp_start": timestamp_start_fmt,
+                        "timestamp_end": self.end.strftime("%Y%m%d%H%M%S"),
+                    },
+                )
+
+                con.execute(metadata_stmt)
+                con.commit()
+
+        return f"{schema_name} table and metadata updated."
+
+    def plot(
+        self, include_outliers: bool = False, ax: Any = None, **plot_kwargs: Any
+    ) -> tuple:
+        """Plots the timeseries data.
+
+        Args:
+            include_outliers (bool): Whether to include outliers in the plot.
+            ax (matplotlib.axes.Axes, optional): Matplotlib axes object to plot on.
+                If None, a new figure and axes are created.
+            **plot_kwargs: Additional keyword arguments passed to plt.plot.
+
+        Returns:
+            (fig, ax): Matplotlib figure and axes to allow further customization.
+        """
+        # Create new figure and axes if not provided
+        if ax is None:
+            fig, ax = plt.subplots(figsize=(10, 5))
+        else:
+            fig = ax.get_figure()
+
+        ax.plot(
+            self.ts.index,
+            self.ts,
+            label=f"{self.location} ({self.sensor})",
+            **plot_kwargs,
+        )
+
+        if include_outliers and self.outliers is not None:
+            ax.scatter(
+                self.outliers.index, self.outliers, color="red", label="Outliers"
+            )
+        plt.xticks(rotation=45)
+        ax.set_xlabel("Time")
+        ax.set_ylabel(f"{self.variable} ({self.unit})")
+        ax.set_title(f"{self.variable.capitalize()} at {self.location}")
+
+        ax.legend()
+
+        return fig, ax

{gensor-0.1.2 → gensor-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "gensor"
-version = "0.1.2"
+version = "0.1.3"
 description = "Library for handling groundwater sensor data."
 authors = ["Mateusz Zawadzki <zawadzkimat@outlook.com>"]
 repository = "https://github.com/zawadzkim/gensor"