polars.Series.bin_quantiles

Series.bin_quantiles(

quantiles: Sequence[float] | int,

*,

labels: Sequence[str_] | Literal[False],

include_intervals: bool = False,

right_closed: bool = False,

) → Series

Bin values into discrete intervals delimited by quantiles of the data.

Warning

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

Parameters:

quantiles

Non-decreasing quantiles in [0, 1], or a positive integer giving the number of bins. Two equal quantiles delimit an empty bin. Input must be numeric. For quantile q, the value of the breakpoint is the sorted value at floor(q * (len - 1)).

labels

One label per bin, or False to return the integer bin index.

include_intervals

Return a struct with fields bin, left, and right. The first bin’s left and last bin’s right boundary are null.

right_closed

Use right-closed (left, right] rather than left-closed [left, right) bins.

Returns:

Series

Series of data type Enum, or UInt32 if labels is False, or Struct if include_intervals is set.

See also

bin_intervals

bin_ranks

Examples

Unlike bin_ranks(), all equal values remain in the same bin, so a bin can be empty. Here the breakpoints are 1, 1, and 2, giving the bins [-inf, 1), [1, 1), [1, 2), and [2, inf). The first is empty because a left-closed bin excludes its right boundary, and the second because the breakpoint 1 repeats.

>>> s = pl.Series("x", [1, 1, 2, 2])
>>> s.bin_quantiles([0.1, 0.25, 0.75], labels=["a", "b", "c", "d"])
shape: (4,)
Series: 'x' [enum]
[
    "c"
    "c"
    "d"
    "d"
]