Metadata-Version: 2.4
Name: polars-distr
Version: 0.2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Requires-Dist: polars>=1.42.1,<1.44
Requires-Dist: numpy>=1.26 ; extra == 'reference'
Requires-Dist: mpmath>=1.3 ; extra == 'tests'
Requires-Dist: numpy>=1.26 ; extra == 'tests'
Requires-Dist: pytest ; extra == 'tests'
Provides-Extra: reference
Provides-Extra: tests
License-File: LICENSE
Summary: Native Polars expressions for piecewise-uniform distribution statistics
Keywords: polars,distribution,probability,statistics,crps
Author-email: Silurian AI <contact@silurian.ai>
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# 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`.

```python
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:

```python
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.

