Introduction

groupby is pandas’ standard tool for computing per-group statistics such as count, mean, min, max, or standard deviation. The basic usage is simple, but real analysis often needs multiple aggregations, renamed outputs, and correct handling of missing values.

The main design choice is how you want the output shaped. For quick exploration, a compact grouped summary is fine. For reusable reports and downstream merges, named aggregations and flattened columns are usually better.

Basic Group Statistics

Start with a simple DataFrame.

1import pandas as pd
2
3df = pd.DataFrame({
4    "team": ["A", "A", "B", "B", "B", "C"],
5    "score": [10, 14, 9, 11, 13, 20],
6    "minutes": [30, 28, 25, 31, 29, 35],
7})
8
9summary = df.groupby("team")["score"].agg(["count", "mean", "min", "max"])
10print(summary)

This produces one row per group and one column per requested statistic.

Aggregate Multiple Columns

You can summarize several columns at once.

1summary = df.groupby("team").agg({
2    "score": ["count", "mean", "std"],
3    "minutes": ["mean", "max"],
4})
5
6print(summary)

This works, but it produces a multi-level column index. That is fine for analysis, but it can become awkward when exporting or joining the result later.

Named Aggregations Give Cleaner Output

Named aggregation is often the best style for reusable code.

1summary = df.groupby("team").agg(
2    score_count=("score", "count"),
3    score_mean=("score", "mean"),
4    score_max=("score", "max"),
5    minutes_mean=("minutes", "mean"),
6)
7
8print(summary.reset_index())

This gives flat column names immediately, which is usually easier for reporting pipelines.

Group by More Than One Key

Real datasets often need grouping on multiple dimensions.

1df2 = pd.DataFrame({
2    "team": ["A", "A", "A", "B", "B"],
3    "season": [2024, 2024, 2025, 2024, 2025],
4    "score": [10, 12, 9, 15, 14],
5})
6
7summary = df2.groupby(["team", "season"]).agg(
8    games=("score", "count"),
9    avg_score=("score", "mean"),
10)
11
12print(summary)

Use reset_index() afterward if you want the keys back as ordinary columns.

Missing Values Change the Meaning

Not all group statistics treat missing values the same way. A common source of confusion is the difference between count and size.

1df3 = pd.DataFrame({
2    "group": ["x", "x", "y"],
3    "value": [1.0, None, 3.0],
4})
5
6print(df3.groupby("group")["value"].count())
7print(df3.groupby("group").size())

count ignores null values in the selected column. size counts rows regardless of nulls. Choose deliberately based on the reporting definition you need.

Custom Statistics

You can supply your own aggregation function when built-in metrics are not enough.

1def value_range(series):
2    return series.max() - series.min()
3
4summary = df.groupby("team").agg(
5    avg_score=("score", "mean"),
6    score_range=("score", value_range),
7)
8
9print(summary)

Custom functions are useful, but they should stay simple and deterministic if you plan to reuse them.

Common Pitfalls

A common mistake is using the default multi-index output and then discovering later that downstream code expected flat column names.

Another issue is confusing count with size in the presence of null values. They answer different questions.

Developers also often forget to call reset_index() before exporting or merging grouped output with another DataFrame.

Finally, custom Python aggregation functions are flexible but can be slower than built-in vectorized operations. Use them when needed, not by default.

It is also easy to forget that group keys may be sorted by default depending on the call pattern. If presentation order matters, sort the result explicitly after aggregation instead of relying on incidental input order.

Summary

• Use pandas groupby plus agg to compute per-group statistics.
• Named aggregations usually produce the cleanest reusable result shape.
• Grouping by multiple keys is straightforward but may create hierarchical indexes.
• Be explicit about null handling, especially the difference between count and size.
• Choose output shape intentionally so the summary remains easy to reuse.