modus-py 0.1.0a1__py3-none-any.whl

modus/__init__.py

@@ -0,0 +1,177 @@
+"""modus — schema-driven, unit-aware Polars transform engine.
+
+modus pairs a Polars `ModusFrame` (a DataFrame with per-column Astropy unit
+metadata) with `FrameTransform`, a builder-pattern engine for expressing
+timeseries transform pipelines — grouping, cleaning, deriving, filtering, and
+aggregating — declaratively, while keeping unit metadata accurate throughout.
+
+Quick start
+-----------
+>>> import astropy.units as u
+>>> import polars
+>>> import modus
+>>>
+>>> frame = modus.ModusFrame(
+...     data=polars.DataFrame({"hoist_pressure1": [101.3, 98.7]}),
+...     units={"hoist_pressure1": u.kPa},
+... )
+>>> velocity = frame.col("distance") / frame.col("time")  # UnitExpr; unit propagates
+>>> frame = frame.with_columns(velocity=velocity)
+
+Public surface
+--------------
+`ModusFrame`
+    Polars DataFrame paired with per-column Astropy unit metadata. Exposes
+    `~ModusFrame.col` to obtain unit-aware expressions and explicit
+    transformation methods (`~ModusFrame.with_columns`, `~ModusFrame.select`,
+    `~ModusFrame.filter`, `~ModusFrame.rename`, `~ModusFrame.drop`,
+    `~ModusFrame.sort`, `~ModusFrame.join`, `~ModusFrame.concat`) that
+    keep the unit dict accurate after each operation.
+
+`UnitExpr`
+    A `polars.Expr` paired with an `u.UnitBase`. Returned by
+    `ModusFrame.col`; supports arithmetic operator overloads (``+``, ``-``,
+    ``*``, ``/``) that propagate unit algebra alongside the Polars expression
+    tree.
+
+:data:`TIMESTAMP_COLUMN`
+    Module-level constant (``"ts"``) naming the canonical timestamp column
+    present in every timeseries `ModusFrame`.
+
+`ModusFrameBuilder`
+    Helper used to construct an `ModusFrame` from raw Polars data and unit
+    strings, parsed via `modus.units.registry`.
+
+`FrameTransform`
+    Schema-driven, unit-aware transform engine. Build up a pipeline with
+    groupers, cleaners, derivations, filters, and aggregations, then call
+    `~FrameTransform.apply` to execute it against an `ModusFrame`. Both a
+    labelled timeseries and a per-event aggregated summary are returned as a
+    `TransformResult`.
+
+`ModusError`, `FrameError`, `TransformError`
+    modus's exception hierarchy — see `modus.errors`.
+
+`modus.units.registry`
+    Shared, extensible unit registry (see `modus.units`). Register custom
+    unit strings against it, Astropy-style, before parsing them.
+
+Transform operations
+---------------------
+- Groupers: `DataGap`, `EventSequence`, `PatternSequence`
+- Cleaners: `FillForward`, `FillBackward`, `FillNull`, `Interpolate`
+- Derivations: `TimeDelta`, `Rate`, `LinearCombination`, `Formula`,
+  `ColumnExpression`, and the `Derivation` extension point with
+  `DerivationRegistry` for declarative construction by name
+- Filters: `SuppressLeadingEvent`, `SuppressTrailingEvent`,
+  `SuppressEventCrossingGrouper`
+- Aggregations: `Mean`, `Sum`, `Sem`, `Min`, `Max`, `MaxAbs`, `Std`, `First`,
+  `Last`, `Mode`, `NthValue`, `ValueSequence`, `Duration`, `Count`, and the
+  `Aggregation` extension point with `AggregationRegistry`
+- Group filters: `GroupCondition`, `GroupFilter`
+- Event views: `EventView`, `Budget`, `Rows`, `Seconds`
+"""
+
+# Local
+from modus import units
+from modus._builder import ModusFrameBuilder
+from modus.errors import FrameError, ModusError
+from modus.expr import UnitExpr
+from modus.frame import TIMESTAMP_COLUMN, ModusFrame
+from modus.transform import (
+    Aggregation,
+    AggregationRegistry,
+    Budget,
+    ColumnExpression,
+    Count,
+    DataGap,
+    Derivation,
+    DerivationRegistry,
+    Duration,
+    EventSequence,
+    EventView,
+    FillBackward,
+    FillForward,
+    FillNull,
+    First,
+    Formula,
+    FrameTransform,
+    GroupCondition,
+    GroupFilter,
+    Interpolate,
+    Last,
+    LinearCombination,
+    Max,
+    MaxAbs,
+    Mean,
+    Min,
+    Mode,
+    NthValue,
+    PatternSequence,
+    Rate,
+    Rows,
+    Seconds,
+    Sem,
+    Std,
+    Sum,
+    SuppressEventCrossingGrouper,
+    SuppressLeadingEvent,
+    SuppressTrailingEvent,
+    TimeDelta,
+    TransformError,
+    TransformResult,
+    ValueSequence,
+)
+
+
+__all__ = [
+    "TIMESTAMP_COLUMN",
+    "Aggregation",
+    "AggregationRegistry",
+    "Budget",
+    "ColumnExpression",
+    "Count",
+    "DataGap",
+    "Derivation",
+    "DerivationRegistry",
+    "Duration",
+    "EventSequence",
+    "EventView",
+    "FillBackward",
+    "FillForward",
+    "FillNull",
+    "First",
+    "Formula",
+    "FrameError",
+    "FrameTransform",
+    "GroupCondition",
+    "GroupFilter",
+    "Interpolate",
+    "Last",
+    "LinearCombination",
+    "Max",
+    "MaxAbs",
+    "Mean",
+    "Min",
+    "Mode",
+    "ModusError",
+    "ModusFrame",
+    "ModusFrameBuilder",
+    "NthValue",
+    "PatternSequence",
+    "Rate",
+    "Rows",
+    "Seconds",
+    "Sem",
+    "Std",
+    "Sum",
+    "SuppressEventCrossingGrouper",
+    "SuppressLeadingEvent",
+    "SuppressTrailingEvent",
+    "TimeDelta",
+    "TransformError",
+    "TransformResult",
+    "UnitExpr",
+    "ValueSequence",
+    "units",
+]

modus/_builder.py

@@ -0,0 +1,61 @@
+"""Builds an `ModusFrame` from raw Polars data and unit strings."""
+
+from __future__ import annotations
+
+# Standard Library
+import collections.abc
+
+# Third Party
+import astropy.units as u
+import polars
+
+# Local
+from modus.errors import FrameError
+from modus.frame import ModusFrame
+from modus.units import registry
+
+
+class ModusFrameBuilder:
+    """Internal helper that builds a `ModusFrame` from raw Polars data
+    and a resolved unit map.
+
+    This is used by the retrieval layer and is not part of the public API.
+    """
+
+    @staticmethod
+    def build(
+        data: polars.DataFrame,
+        column_units: collections.abc.Mapping[str, str],
+    ) -> ModusFrame:
+        """Build a `ModusFrame` from a Polars DataFrame and unit strings.
+
+        Parameters
+        ----------
+        data:
+            Raw Polars DataFrame with canonical column names.
+        column_units:
+            Mapping of column name to Astropy-compatible unit string
+            (e.g. ``"kPa"``, ``"kph"``).
+
+        Returns
+        -------
+        ModusFrame
+            Frame with parsed Astropy units.
+
+        Raises
+        ------
+        FrameError
+            When a unit string cannot be parsed by Astropy.
+        """
+        parsed: dict[str, u.UnitBase] = {}
+        for col, unit_str in column_units.items():
+            if not unit_str:
+                continue
+            try:
+                parsed[col] = registry.parse(unit_str)
+            except Exception as exc:
+                raise FrameError(f"Cannot parse unit string {unit_str!r} for column {col!r}: {exc}") from exc
+        return ModusFrame(data=data, units=parsed)
+
+
+__all__ = ["ModusFrameBuilder"]

modus/errors.py

@@ -0,0 +1,37 @@
+"""modus exceptions."""
+
+from __future__ import annotations
+
+
+class ModusError(Exception):
+    """Base class for all modus exceptions."""
+
+
+class FrameError(ModusError):
+    """Raised for `ModusFrame` construction or structural validation failures.
+
+    Covers unparseable unit strings in frame definitions, malformed JSON
+    envelopes, and other structural validation failures detected during
+    frame initialization.
+    """
+
+
+class IncompatibleUnitsError(ModusError):
+    """Raised when an operation encounters a physical dimensional mismatch.
+
+    Fired immediately at expression-build time when performing binary
+    operations between incompatible physical dimensions (e.g., adding
+    meters to seconds) on a `UnitExpr`.
+    """
+
+
+class InvalidTransformSchemaError(FrameError):
+    """"""
+
+
+__all__ = [
+    "FrameError",
+    "IncompatibleUnitsError",
+    "InvalidTransformSchemaError",
+    "ModusError",
+]

modus/expr.py

@@ -0,0 +1,149 @@
+"""UnitExpr — Polars expression paired with an Astropy unit."""
+
+from __future__ import annotations
+
+# Standard Library
+import dataclasses
+import typing
+
+# Third Party
+import astropy.units as u
+import polars
+
+# Local
+from modus.errors import IncompatibleUnitsError
+
+
+# Types that can appear on the right-hand side of a UnitExpr operation.
+_Operand = typing.Union["UnitExpr", u.Quantity, int, float]
+
+
+@dataclasses.dataclass(repr=False, eq=False, slots=True)
+class UnitExpr:
+    """A Polars expression paired with an Astropy physical unit.
+
+    `UnitExpr` overloads standard Python arithmetic operators to propagate
+    unit algebra alongside the underlying Polars expression tree. Unit
+    compatibility checks and dimensional algebra are evaluated immediately at
+    expression-build time, raising errors before any data processing or data
+    evaluation occurs within Polars.
+
+    Parameters
+    ----------
+    expr : polars.Expr
+        The underlying Polars expression tree.
+    unit : u.UnitBase
+        The Astropy unit associated with this expression root.
+
+    Examples
+    --------
+    >>> import polars as pl
+    >>> import astropy.units as u
+    >>> from modus.expr import UnitExpr
+    >>> # Simulating an expression generated from a ModusFrame
+    >>> distance = UnitExpr(pl.col("distance"), u.m)
+    >>> time = UnitExpr(pl.col("time"), u.s)
+    >>> velocity = distance / time
+    >>> velocity
+    <UnitExpr unit='m / s'>
+    """
+
+    expr: polars.Expr
+    unit: u.UnitBase
+
+    def __add__(self, other: _Operand) -> UnitExpr:
+        other_expr, other_unit = self._decompose(other)
+        if isinstance(other, (int, float)):
+            raise TypeError(
+                "Cannot add a bare scalar to a UnitExpr: the physical meaning is ambiguous. "
+                "Wrap the scalar as an astropy Quantity (e.g. 5 * u.m) to make units explicit."
+            )
+        if not self.unit.is_equivalent(other_unit):
+            raise IncompatibleUnitsError(f"Incompatible units for addition: {self.unit!r} + {other_unit!r}.")
+        return UnitExpr(expr=self.expr + other_expr, unit=self.unit)
+
+    def __radd__(self, other: _Operand) -> UnitExpr:
+        return self.__add__(other)
+
+    def __sub__(self, other: _Operand) -> UnitExpr:
+        other_expr, other_unit = self._decompose(other)
+        if isinstance(other, (int, float)):
+            raise TypeError(
+                "Cannot subtract a bare scalar from a UnitExpr: the physical meaning is ambiguous. "
+                "Wrap the scalar as an astropy Quantity (e.g. 5 * u.m) to make units explicit."
+            )
+        if not self.unit.is_equivalent(other_unit):
+            raise IncompatibleUnitsError(f"Incompatible units for subtraction: {self.unit!r} - {other_unit!r}.")
+        return UnitExpr(expr=self.expr - other_expr, unit=self.unit)
+
+    def __rsub__(self, other: _Operand) -> UnitExpr:
+        other_expr, other_unit = self._decompose(other)
+        if isinstance(other, (int, float)):
+            raise TypeError(
+                "Cannot subtract a UnitExpr from a bare scalar: the physical meaning is ambiguous. "
+                "Wrap the scalar as an astropy Quantity (e.g. 5 * u.m) to make units explicit."
+            )
+        if not self.unit.is_equivalent(other_unit):
+            raise IncompatibleUnitsError(f"Incompatible units for subtraction: {other_unit!r} - {self.unit!r}.")
+        return UnitExpr(expr=other_expr - self.expr, unit=self.unit)
+
+    def __mul__(self, other: _Operand) -> UnitExpr:
+        other_expr, other_unit = self._decompose(other)
+        return UnitExpr(expr=self.expr * other_expr, unit=self.unit * other_unit)
+
+    def __rmul__(self, other: _Operand) -> UnitExpr:
+        return self.__mul__(other)
+
+    def __truediv__(self, other: _Operand) -> UnitExpr:
+        other_expr, other_unit = self._decompose(other)
+        return UnitExpr(expr=self.expr / other_expr, unit=self.unit / other_unit)
+
+    def __rtruediv__(self, other: _Operand) -> UnitExpr:
+        other_expr, other_unit = self._decompose(other)
+        return UnitExpr(expr=other_expr / self.expr, unit=other_unit / self.unit)
+
+    def __repr__(self) -> str:
+        return f"<UnitExpr unit='{self.unit}'>"
+
+    @staticmethod
+    def _decompose(operand: _Operand) -> tuple[polars.Expr, u.UnitBase]:
+        """Decompose an arithmetic operand into its Polars expression and Astropy unit components.
+
+        Parameters
+        ----------
+        operand : UnitExpr | u.Quantity | int | float
+            The operand to evaluate and convert into valid expression components.
+            Supported combinations map as follows:
+
+            - `UnitExpr`: Extracts the underlying components directly.
+            - `u.Quantity`: Wraps the quantity's array or scalar value
+              as a `polars.lit` expression and returns its physical unit metadata.
+            - `int` or `float`: Handled as an unscaled, dimensionless literal
+              value (`u.dimensionless_unscaled`).
+
+        Returns
+        -------
+        expr : polars.Expr
+            A Polars expression tree component corresponding to the operand value or column reference.
+        unit : u.UnitBase
+            The Astropy physical unit tracking data associated with the operand component.
+
+        Raises
+        ------
+        TypeError
+            If the `operand` is not one of the strictly supported arithmetic types
+            (e.g., passing raw string literals, dicts, or un-aliased standard dataframes).
+        """
+        if isinstance(operand, UnitExpr):
+            return operand.expr, operand.unit
+        if isinstance(operand, u.Quantity):
+            return polars.lit(operand.value), operand.unit
+        if isinstance(operand, (int, float)):
+            return polars.lit(operand), u.dimensionless_unscaled
+        raise TypeError(
+            f"Unsupported operand type for UnitExpr arithmetic: {type(operand).__name__}. "
+            "Expected UnitExpr, astropy Quantity, int, or float."
+        )
+
+
+__all__ = ["UnitExpr"]