Skip to main content
v2026.11,986 entries · CC-BY 4.0

pandas agg: groupby().agg(), Named Aggregation and Examples

pandas agg (an alias of aggregate) reduces a DataFrame or groupby object to summary statistics. Syntax, named aggregation, dict and list forms, NaN output and troubleshooting.

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.

Ask your first question freeSubscribe

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; 1 applies 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],
})
  1. Group the rows with df.groupby("arm").
  2. Call agg with 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"),
    )
  3. 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
  4. Keep the group key as a column if you plan to merge or export: pass as_index=False to groupby.

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 with def so 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=False or 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

Documentation consulted November 2026 (pandas 3.1 docs; examples run on pandas 3.0.5).

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about pandas agg: groupby().agg(), Named Aggregation and Examples

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →