Introduction

Column naming during aggregation in pandas can become confusing when you apply multiple functions per column. Without a naming strategy, output often contains MultiIndex columns that are hard to use downstream. This guide shows clear, production-friendly ways to control names from groupby().agg().

Why Aggregation Names Matter

Aggregated tables are usually fed into reporting, joins, or machine learning features. If columns are ambiguously named, later code becomes brittle and easy to break.

Example of default behavior:

1import pandas as pd
2
3df = pd.DataFrame(
4    {
5        "team": ["A", "A", "B", "B"],
6        "points": [10, 20, 15, 25],
7        "assists": [5, 7, 6, 9],
8    }
9)
10
11result = df.groupby("team").agg({"points": ["mean", "max"], "assists": ["sum"]})
12print(result)
13print(result.columns)

This creates nested column labels, which can be fine for exploration but awkward for stable pipelines.

Best Practice: Named Aggregation

Named aggregation lets you define final column names explicitly.

1summary = (
2    df.groupby("team", as_index=False)
3      .agg(
4          avg_points=("points", "mean"),
5          max_points=("points", "max"),
6          total_assists=("assists", "sum"),
7      )
8)
9
10print(summary)

This is the cleanest option in modern pandas because output names are readable and deterministic.

Mixing Built-in and Custom Aggregations

You can combine built-in functions with custom callables while still naming output columns.

1import numpy as np
2
3summary = (
4    df.groupby("team", as_index=False)
5      .agg(
6          avg_points=("points", "mean"),
7          p90_points=("points", lambda s: np.percentile(s, 90)),
8          assist_range=("assists", lambda s: s.max() - s.min()),
9      )
10)
11
12print(summary)

For complex custom logic, define named functions instead of inline lambdas to improve maintainability.

Renaming After MultiIndex Output

If you already have a MultiIndex result, flatten and rename after aggregation.

1multi = df.groupby("team").agg({"points": ["mean", "max"], "assists": ["sum", "mean"]})
2
3multi.columns = ["_".join(col).strip("_") for col in multi.columns.to_flat_index()]
4multi = multi.reset_index()
5
6rename_map = {
7    "points_mean": "avg_points",
8    "points_max": "max_points",
9    "assists_sum": "total_assists",
10    "assists_mean": "avg_assists",
11}
12
13multi = multi.rename(columns=rename_map)
14print(multi)

This approach is useful for legacy notebooks where aggregation style is already established.

Handling Duplicate Column Names Safely

If your input DataFrame has duplicate column labels, aggregation can become ambiguous. Standardize columns first.

1def dedupe_columns(columns):
2    seen = {}
3    out = []
4    for c in columns:
5        n = seen.get(c, 0)
6        out.append(c if n == 0 else f"{c}_{n}")
7        seen[c] = n + 1
8    return out
9
10raw = pd.DataFrame([[1, 2]], columns=["value", "value"])
11raw.columns = dedupe_columns(raw.columns)
12print(raw.columns)

Stable naming upstream prevents subtle aggregation failures downstream.

Grouped Aggregation with Multiple Keys

Real datasets often group by more than one dimension, such as region and month. Named aggregation still works well and keeps final columns stable for downstream joins.

1monthly = pd.DataFrame(
2    {
3        "region": ["East", "East", "West", "West"],
4        "month": ["2026-01", "2026-02", "2026-01", "2026-02"],
5        "revenue": [100, 120, 90, 130],
6    }
7)
8
9out = (
10    monthly.groupby(["region", "month"], as_index=False)
11           .agg(total_revenue=("revenue", "sum"), avg_revenue=("revenue", "mean"))
12)
13print(out)

If your team exports aggregates to CSV or BI tools, explicit names are especially important because many tools flatten columns differently. Naming in pandas itself avoids those inconsistencies.

Common Pitfalls

A common pitfall is relying on default aggregation column names and then hardcoding positional column access later. This breaks when functions are added or reordered.

Another issue is using anonymous lambdas everywhere. Pandas labels them poorly in some contexts, producing unreadable output. Prefer named aggregation keys.

Developers also forget as_index=False, then later need extra resets before joins. Decide early whether grouped keys should remain index or columns.

Finally, avoid mixing old dict aggregation syntax and new named aggregation style inconsistently in one codebase. Standardize style to improve team readability.

Summary

• Use named aggregation to control output column names directly.
• Keep aggregation outputs stable for reporting and joins.
• Flatten and rename MultiIndex columns when working with legacy code.
• Standardize duplicate source column names before aggregation.
• Prefer explicit names over implicit defaults for long-term maintainability.