narwhals.GroupBy

agg(*aggs, **named_aggs)

Compute aggregations for each group of a group by operation.

Parameters:

Name	Type	Description	Default
aggs	IntoExpr | Iterable[IntoExpr]	Aggregations to compute for each group of the group by operation, specified as positional arguments.	()
named_aggs	IntoExpr	Additional aggregations, specified as keyword arguments.	{}

Examples:

Group by one column or by multiple columns and call agg to compute the grouped sum of another column.

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> df_pd = pd.DataFrame(
...     {
...         "a": ["a", "b", "a", "b", "c"],
...         "b": [1, 2, 1, 3, 3],
...         "c": [5, 4, 3, 2, 1],
...     }
... )
>>> df_pl = pl.DataFrame(
...     {
...         "a": ["a", "b", "a", "b", "c"],
...         "b": [1, 2, 1, 3, 3],
...         "c": [5, 4, 3, 2, 1],
...     }
... )

We define library agnostic functions:

>>> def func(df_any):
...     df = nw.from_native(df_any)
...     df = df.group_by("a").agg(nw.col("b").sum()).sort("a")
...     return nw.to_native(df)

>>> def func_mult_col(df_any):
...     df = nw.from_native(df_any)
...     df = df.group_by("a", "b").agg(nw.sum("c")).sort("a", "b")
...     return nw.to_native(df)

We can then pass either pandas or Polars to func and func_mult_col:

>>> func(df_pd)
   a  b
0  a  2
1  b  5
2  c  3
>>> func(df_pl)
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ a   ┆ 2   │
│ b   ┆ 5   │
│ c   ┆ 3   │
└─────┴─────┘
>>> func_mult_col(df_pd)
   a  b  c
0  a  1  8
1  b  2  4
2  b  3  2
3  c  3  1
>>> func_mult_col(df_pl)
shape: (4, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 1   ┆ 8   │
│ b   ┆ 2   ┆ 4   │
│ b   ┆ 3   ┆ 2   │
│ c   ┆ 3   ┆ 1   │
└─────┴─────┴─────┘