polars-distr 0.2.0

Native Polars expressions for piecewise-uniform distribution statistics

polars-distr

Native Polars expressions for statistics over piecewise-uniform distributions. The plugin computes means, CDF values, quantiles, and exact CRPS inside lazy and streaming query plans without Python UDFs.

Install with uv add polars-distr or pip install polars-distr.

import polars as pl
import polars_distr as pld  # registers the Distribution dtype

result = (
    pl.scan_parquet("distributions.parquet")
    .select(
        pld.quantiles("distribution", [0.1, 0.5, 0.9]).alias("quantiles"),
        pld.crps("distribution", "observation").alias("crps"),
    )
    .collect(engine="streaming")
)

Constructing distributions

distribution() accepts either paired fixed-width Array columns or paired variable-width List columns:

distribution = pld.distribution("weights", "edges")

It produces the logical Distribution dtype with serialized identity polars_distr.piecewise_uniform.v1. Its storage is a Struct with exactly weights and edges, in that order. Fixed storage must be Array/Array with edge width equal to weight width plus one. Ragged storage must be List/List. Mixed layouts are rejected by the constructor and statistics kernels.

Integer, Float32, and Float64 child values are supported. Invalid distribution rows produce null results; statically invalid schemas raise during schema resolution. Raw paired Struct storage is also accepted by every statistics kernel for interoperability.

v0.2 breaking changes

• The public vocabulary is distribution, weights, and edges; the v0.1 histogram and counts names are removed.
• The extension identity is polars_distr.piecewise_uniform.v1. Data written with the pre-contract polars_distr.distribution.v1 identity is not guaranteed to load.
• distribution() accepts paired Array/Array and paired List/List storage. Mixed Array/List storage is rejected.