Written and maintained by CASRAI Editorial Board
Published
On this page
pandas agg (also written aggregate pandas or pandas aggregate) is the pandas method that reduces a Series, DataFrame or grouped object to summary values such as a sum, mean, minimum or standard deviation. agg is an alias for aggregate; the pandas documentation says to use the alias. Called on a DataFrame it summarises each column (or each row); called after groupby() it produces one summary row per group, which is the usual route to a per-arm, per-site or per-year results table.
Ask CASRAI · free to tryQuestion about this guide? Ask CASRAI answers with linked sources. 2 free questions a day, no account.
What pandas agg is used for in research
Most analysis scripts need a table of descriptive statistics split by a grouping variable: n, mean and standard deviation per treatment arm, median age per site, maximum concentration per sample batch. DataFrame.agg and DataFrameGroupBy.agg build that table in one call and let you name the output columns. For the underlying statistics see descriptive statistics; for data that must be reshaped before or after aggregation see pandas pivot and pandas melt, and for the layout that makes grouping straightforward see tidy data rules.
Install or access
pandas is open-source software distributed by the pandas project. The official installation page documents pip install pandas and conda install -c conda-forge pandas. Then import it in your script or notebook:
import pandas as pd
The syntax below follows the pandas 3.1 documentation, and the worked outputs were run on pandas 3.0.5. Check your version with pd.__version__ if a result differs.
Syntax and arguments
DataFrame.agg(func=None, axis=0, *args, **kwargs)
- func: a function, a string naming a function, a list of functions or names, or a dict mapping axis labels (column names) to functions. If omitted, keyword arguments are used for named aggregation (below).
- axis:
0(default) applies the function to each column;1applies it to each row. - *args, **kwargs: additional arguments passed to the function, or output names in named aggregation.
The return type depends on the input: a scalar when a single function is applied to a Series, a Series when a single function is applied to a DataFrame, and a DataFrame when several functions are passed. Unlike NumPy, which by default aggregates over the flattened array, agg aggregates along an axis. A user-defined function receives a Series, and functions that mutate the Series they are given are not supported.
Step-by-step: a per-group summary table
The data below are a small synthetic example invented for this page (not from any real study): systolic blood pressure and age for six participants in two arms.
import pandas as pd
df = pd.DataFrame({
"arm": ["control", "control", "control", "treatment", "treatment", "treatment"],
"site": ["A", "B", "A", "A", "B", "B"],
"sbp": [132, 141, 128, 125, 119, 130],
"age": [54, 61, 47, 58, 50, 66],
})
- Group the rows with
df.groupby("arm"). - Call
aggwith named aggregation. Each keyword becomes an output column; each value is a(column, function)tuple:summary = df.groupby("arm").agg( n=("sbp", "count"), mean_sbp=("sbp", "mean"), sd_sbp=("sbp", "std"), max_age=("age", "max"), ) - Read the result. One row per group, columns named as you chose:
n mean_sbp sd_sbp max_age arm control 3 133.666667 6.658328 61 treatment 3 124.666667 5.507571 66 - Keep the group key as a column if you plan to merge or export: pass
as_index=Falsetogroupby.
pd.NamedAgg(column="sbp", aggfunc="mean") is an equivalent, more explicit spelling of the tuple. If an output name is not a valid Python identifier (for example it contains a space), pass it by unpacking a dict: agg(**{"mean sbp": pd.NamedAgg("sbp", "mean")}).
Choosing the form: which call gives which output
| Goal | Call | Output shape |
|---|---|---|
| One statistic for every column | df.agg("mean") |
Series, one value per column |
| Several statistics for every column | df.agg(["mean", "min"]) |
DataFrame, one row per function |
| Different statistics per column | df.agg({"sbp": ["mean", "min"], "age": "max"}) |
DataFrame, NaN where a statistic was not requested for a column |
| Per-row statistic | df[["sbp", "age"]].agg("mean", axis="columns") |
Series, one value per row |
| Per-group table with chosen column names | df.groupby("arm").agg(n=("sbp", "count")) |
DataFrame, one row per group |
| Several statistics for one grouped column | df.groupby("arm")["sbp"].agg(["count", "mean", "std"]) |
DataFrame, one column per function |
| Several statistics for several grouped columns | df.groupby("arm").agg({"sbp": ["mean", "std"], "age": "median"}) |
DataFrame with hierarchical (two-level) column labels |
Output and how to read it
Why dict and list forms on a DataFrame contain NaN
When you aggregate a whole DataFrame with a dict, the result is a single table whose rows are the union of all requested functions. Cells for a function you did not request on a given column are filled with NaN. With the example data, df[["sbp","age"]].agg({"sbp": ["mean","min"], "age": ["max"]}) returns:
sbp age
mean 129.166667 NaN
min 119.000000 NaN
max NaN 66.0
These NaN values mean “not requested”, not “missing data”. The same layout appears with keyword (named) aggregation on an ungrouped DataFrame, where each output row has a value only in its own column. After groupby, named aggregation gives the compact per-group table shown earlier.
Hierarchical columns
Passing a list of functions to a DataFrameGroupBy, or a dict of lists, yields two-level column labels such as ("sbp", "mean"). Select with summary[("sbp", "mean")], or avoid the extra level by using named aggregation or a list on a single selected column (df.groupby("arm")["sbp"].agg([...])).
Renaming outputs
On a grouped Series you can pass a list of (name, function) tuples, or chain .rename(columns=...). Named aggregation is the clearest route.
Troubleshooting
- Output columns called
<lambda_0>,<lambda_1>. Several lambdas in one list receive generated names. Give them names with named aggregation, or define functions withdefso the function name is used. - Extra arguments are ignored in named aggregation. The pandas user guide states that extra keyword arguments given to named aggregation are not passed to the aggregation functions. Wrap the function:
functools.partial(func, arg=value). - String names must be valid methods. A string such as
"mean"or"sum"must name a method pandas can apply to the object. Otherwise pass a callable. - Group key missing from the columns. By default the grouping column becomes the index. Use
as_index=Falseor call.reset_index(). - Relabelling the index fails. Relabelling the result index with named aggregation requires
axis=0. - Slow with a custom function. User-defined aggregations are typically slower than built-in methods; use built-ins (
"mean","std") where one exists. Do not modify the Series your function receives. - Need a per-row transformation, not a reduction. Use apply, or rolling windows for moving statistics. If your goal is to remove repeated records first, see pandas drop duplicates.
Free alternatives
| Tool | Equivalent of a grouped summary |
|---|---|
| pandas | df.groupby("arm").agg(...) |
| Polars (Python) | df.group_by("arm").agg(...) |
| R (base) | aggregate(sbp ~ arm, data = df, FUN = mean) |
| R (dplyr) | df |> group_by(arm) |> summarise(...) |
For a comparison of the two Python libraries see Polars vs pandas.
Frequently asked questions
Is agg the same as aggregate in pandas?
Yes. agg is an alias of aggregate, and the pandas documentation recommends using the alias.
How do I use agg after groupby?
Call df.groupby("key").agg(...) with a function name, a list, a dict, or named aggregation keywords. The result has one row per group.
How do I apply different functions to different columns?
Pass a dict, {"sbp": ["mean", "std"], "age": "median"}, or use named aggregation: agg(mean_sbp=("sbp","mean"), median_age=("age","median")).
How do I rename the output columns?
Use named aggregation; the keyword is the output column name. Alternatively use a list of (name, function) tuples on a grouped Series, or .rename(columns=...).
Can I aggregate across rows instead of columns?
Yes: axis=1 (or axis="columns") applies the function to each row.
Why does my agg result contain NaN?
With a dict or named aggregation on an ungrouped DataFrame, cells for statistics you did not request on that column are NaN. If a column has missing inputs, most built-in statistics skip them by default.
Sources
- pandas documentation: DataFrame.agg
- pandas user guide: Group by (aggregation and named aggregation)
- pandas documentation: NamedAgg
Documentation consulted November 2026 (pandas 3.1 docs; examples run on pandas 3.0.5).







