polars.fold

polars.fold(

acc: IntoExpr,

function: Callable[[Series, Series], Series],

exprs: Sequence[Expr | str] | Expr,

*,

returns_scalar: bool = False,

return_dtype: DataTypeExpr | PolarsDataType | None = None,

) → Expr

Accumulate over multiple columns horizontally/ row wise with a left fold.

Parameters:

acc

Accumulator Expression. This is the value that will be initialized when the fold starts. For a sum this could for instance be lit(0).

function

Function to apply over the accumulator and the value. Fn(acc, value) -> new_value

exprs

Expressions to aggregate over. May also be a wildcard expression.

returns_scalar

Whether or not function applied returns a scalar. This must be set correctly by the user.

return_dtype

Output datatype. If not set, the dtype will be inferred based on the dtype of the accumulator.

Notes

If you simply want the first encountered expression as accumulator, consider using reduce.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": [3, 4, 5],
...         "c": [5, 6, 7],
...     }
... )
>>> df
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 3   ┆ 5   │
│ 2   ┆ 4   ┆ 6   │
│ 3   ┆ 5   ┆ 7   │
└─────┴─────┴─────┘

Horizontally sum over all columns and add 1.

>>> df.select(
...     pl.fold(
...         acc=pl.lit(1), function=lambda acc, x: acc + x, exprs=pl.col("*")
...     ).alias("sum"),
... )
shape: (3, 1)
┌─────┐
│ sum │
│ --- │
│ i64 │
╞═════╡
│ 10  │
│ 13  │
│ 16  │
└─────┘

You can also apply a condition/predicate on all columns:

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": [0, 1, 2],
...     }
... )
>>> df
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 0   │
│ 2   ┆ 1   │
│ 3   ┆ 2   │
└─────┴─────┘

>>> df.filter(
...     pl.fold(
...         acc=pl.lit(True),
...         function=lambda acc, x: acc & x,
...         exprs=pl.col("*") > 1,
...     )
... )
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 3   ┆ 2   │
└─────┴─────┘