modus-py 0.1.0a2

Schema-driven, unit-aware Polars transform engine.

modus

Schema-driven, unit-aware Polars transform engine.

modus pairs ModusFrame — a Polars 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.

Installation

pip install modus-py

Quick start

import astropy.units as u
import polars
import modus

frame = modus.ModusFrame(
    data=polars.DataFrame({"pressure_kpa": [101.3, 98.7]}),
    units={"pressure_kpa": u.kPa},
)

velocity = frame.col("distance") / frame.col("time")  # UnitExpr; unit propagates
frame = frame.with_columns(velocity=velocity)

import modus
from modus.transform.ops import aggregations, cleaners, filters, groupers

result = (
    modus.FrameTransform()
    .add_grouper(groupers.DataGap("chunk", gap_seconds=60))
    .add_grouper(groupers.EventSequence("body_up_event", source="sts", value=1, within="chunk"))
    .add_cleaner(cleaners.Interpolate("pressure_kpa_kpa", within="chunk"))
    .add_filter(filters.SuppressLeadingEvent("body_up_event", within_column="chunk"))
    .add_filter(filters.SuppressTrailingEvent("body_up_event", within_column="chunk"))
    .group_by("chunk", "body_up_event")
    .add_aggregation(aggregations.Mean("pressure_kpa_kpa", output_name="mean_pressure_kpa_kpa"))
    .add_aggregation(aggregations.Duration(output_name="body_up_duration_s"))
    .apply(frame)
)

labelled = result.labelled      # ModusFrame -- timeseries with grouper columns added
aggregated = result.aggregated  # ModusFrame -- one row per (chunk, body_up_event) group

Documentation

See docs/ for the full reference: ModusFrame/UnitExpr, the unit registry, FrameTransform's execution model and pre-flight validation, each operation family (groupers, cleaners, derivations, filters, group filters, event views, aggregations), the declarative TransformSpec schema, and JSON serialisation.

Custom units

modus ships an extensible unit registry, in the same spirit as Astropy's own enabled-units model:

import astropy.units as u
import modus

modus.units.registry.register("kgcm2", u.def_unit("kgcm2", 98.0665 * u.kPa))

Custom derivations and aggregations

Both extension points are plugin registries keyed by name, so a schema or manifest layer built on top of modus can construct bespoke operations from declarative configuration without importing analytic-specific Python:

import modus

@modus.transform.DerivationRegistry.register("state_inference")
class StateInferenceDerivation(modus.transform.Derivation):
    ...

@modus.transform.AggregationRegistry.register("weighted_percentile")
class WeightedPercentile(modus.transform.Aggregation):
    ...

Development

pip install -e .[dev]
pytest

Licence

BSD-3-Clause — see LICENSE.