polars.Expr.hist

Expr.hist(
    bins: IntoExpr | None = None,
    *,
    bin_count: int | None = None,
    include_category: bool = False,
    include_breakpoint: bool = False,
) → Expr

Bin values into buckets and count their occurrences.

engine:In Memory

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Parameters:

bins

Bin edges. If None given, we determine the edges based on the data.

bin_count

If bins is not provided, bin_count uniform bins are created that fully encompass the data.

include_breakpoint

Include a column that indicates the upper breakpoint.

include_category

Include a column that shows the intervals as categories.

Returns:

DataFrame

Examples

>>> df = pl.DataFrame({"a": [1, 3, 8, 8, 2, 1, 3]})
>>> df.select(pl.col("a").hist(bins=[1, 2, 3]))
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 3   │
│ 2   │
└─────┘
>>> df.select(
...     pl.col("a").hist(
...         bins=[1, 2, 3], include_breakpoint=True, include_category=True
...     )
... )
shape: (2, 1)
┌──────────────────────┐
│ a                    │
│ ---                  │
│ struct[3]            │
╞══════════════════════╡
│ {2.0,"[1.0, 2.0]",3} │
│ {3.0,"(2.0, 3.0]",2} │
└──────────────────────┘