polars.apply#

polars.apply( exprs: Sequence[str | Expr], function: Callable[[Sequence[Series]], Series | Any], return_dtype: PolarsDataType | None = None, *, returns_scalar: bool = True, ) → Expr[source]#

Apply a custom/user-defined function (UDF) in a GroupBy context.

Warning

This method is much slower than the native expressions API. Only use it if you cannot implement your logic otherwise.

Depending on the context it has the following behavior:

Select
Don’t use apply, use map
GroupBy
expected type f: Callable[[Series], Series] Applies a python function over each group.

Parameters:

exprs: Input Series to f
function: Function to apply over the input
return_dtype: dtype of the output Series
returns_scalar: If the function returns a single scalar as output.

Returns:

Expr: Expression with the data type given by return_dtype.

Examples

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

Calculate product of a.

>>> df.with_columns(  
...     pl.col("a").apply(lambda x: x * x).alias("product_a")
... )
shape: (4, 3)
┌─────┬─────┬───────────┐
│ a   ┆ b   ┆ product_a │
│ --- ┆ --- ┆ ---       │
│ i64 ┆ i64 ┆ i64       │
╞═════╪═════╪═══════════╡
│ 7   ┆ 2   ┆ 49        │
│ 2   ┆ 5   ┆ 4         │
│ 3   ┆ 6   ┆ 9         │
│ 4   ┆ 7   ┆ 16        │
└─────┴─────┴───────────┘