Getting started¶

The 60-second version: install, evaluate one distribution, know where to go next. For a guided build of something real, take the tutorial instead.

Install¶

pip install polars-stats

Requires Python >=3.10 and polars>=1.15. Wheels cover Linux, macOS, and Windows; there is nothing to compile. To build from source instead, see Contributing.

Evaluate a distribution¶

Pick a class, parameterise it, call a method. Every method returns a pl.Expr, so it goes wherever an expression goes:

import polars as pl
import polars_stats as ps

dist = ps.Normal(mu=0.0, sigma=1.0)

df = pl.DataFrame({"x": [-1.0, 0.0, 1.0]})

print(
    df.with_columns(
        density=dist.pdf("x"),
        upper_tail=dist.sf("x"),
    )
)

shape: (3, 3)
┌──────┬──────────┬────────────┐
│ x    ┆ density  ┆ upper_tail │
│ ---  ┆ ---      ┆ ---        │
│ f64  ┆ f64      ┆ f64        │
╞══════╪══════════╪════════════╡
│ -1.0 ┆ 0.241971 ┆ 0.841345   │
│ 0.0  ┆ 0.398942 ┆ 0.5        │
│ 1.0  ┆ 0.241971 ┆ 0.158655   │
└──────┴──────────┴────────────┘

Parameters are named after the distribution's own convention (mu / sigma, min / max, a / b), and each class docstring gives the scipy.stats translation. A str argument such as pdf("x") is a column reference, identical to pdf(pl.col("x")).

Parameters can be columns¶

Any parameter accepts a column, so one instance describes a different distribution per row:

per_row = pl.DataFrame({"mu": [0.0, 10.0], "sigma": [1.0, 2.0], "x": [0.5, 11.2]})

print(per_row.with_columns(density=ps.Normal(mu="mu", sigma="sigma").pdf("x")))

shape: (2, 4)
┌──────┬───────┬──────┬──────────┐
│ mu   ┆ sigma ┆ x    ┆ density  │
│ ---  ┆ ---   ┆ ---  ┆ ---      │
│ f64  ┆ f64   ┆ f64  ┆ f64      │
╞══════╪═══════╪══════╪══════════╡
│ 0.0  ┆ 1.0   ┆ 0.5  ┆ 0.352065 │
│ 10.0 ┆ 2.0   ┆ 11.2 ┆ 0.166612 │
└──────┴───────┴──────┴──────────┘

Each row got its own Normal, and the density came back as an ordinary column you can filter, join, or aggregate on.

Where to next¶

• Tutorial: build a per-row anomaly detector end to end, in seven steps.
• How-to guides: recipes for parameters from columns, lazy queries, sampling, nulls, and migrating from scipy.stats.
• API reference: the distribution catalogue, the method surface, and the input contracts.
• Explanation: why the library exists and how it is built.