如何在 Pandas 中构建按类别对齐的表格化报告（索引对齐拼接）_技术教程

本文介绍一种基于 `groupby().cumcount()` 辅助合并的技巧，实现两个含重复类别的 dataframe 按“类别+组内序号”双重键对齐拼接，生成便于 streamlit 等前端直接渲染的结构化对比报表。

在构建分析型报表（尤其是面向非技术用户的展示场景）时，常需将多个来源的同类数据（如不同时间点、不同渠道、不同模型的指标）按逻辑分组对齐呈现。但标准的 pd.merge() 仅支持列级等值连接，pd.concat() 则默认按行位置堆叠——二者均无法满足「同一类别下，第1条记录与第1条记录对齐、第2条与第2条对齐」的精细化对齐需求。

解决这一问题的核心思路是：为每个 DataFrame 的每组 class 内部生成一个稳定的、可对齐的序号列（即组内累计序号），再以此作为辅助连接键进行外连接。Pandas 的 cumcount() 方法恰好能高效完成该任务。

以下是完整实现步骤：

✅ 步骤一：构造示例数据

import pandas as pd

df1 = pd.DataFrame({
    'class': ['A', 'A', 'B', 'X'],
    'item':  ['_1', '_2', '_3', '_4'],
    'value': [10, 11, 12, 13]
})

df2 = pd.DataFrame({
    'class': ['A', 'B', 'B', 'C'],
    'item':  ['_5', '_6', '_7', '_8'],
    'value': [20, 21, 22, 23]
})

✅ 步骤二：使用 cumcount() 构造对齐键并执行外连接

out = (
    df1.merge(
        df2,
        how='outer',
        left_on=['class', df1.groupby('class').cumcount()],
        right_on=['class', df2.groupby('class').cumcount()],
        suffixes=('_1', '_2')
    )
    .sort_values('class')  # 按 class 排序保证可读性
    .drop('key_1', axis=1, errors='ignore')  # 删除 merge 自动生成的临时键列（若存在）
    .reset_index(drop=True)
)

? 关键说明： df1.groupby('class').cumcount() 为 df1 中每个 class 组内的行分配 0, 1, 2, ... 序号；同理 df2.groupby('class').cumcount() 生成 df2 的对应序号； left_on 和 right_on 共同构成复合连接键 ('class', 序号)，确保 A-0 只与 A-0 匹配，A-1 只与 A-1 匹配，从而实现逐行对齐； how='outer' 保留所有类别及所有组内行（包括某一方缺失的情况），配合 NaN 填充未匹配字段。

✅ 输出结果验证

print(out)
#   class item_1  value_1 item_2  value_2
# 0     A     _1     10.0     _5     20.0
# 1     A     _2     11.0    NaN      NaN
# 2     B     _3     12.0     _6     21.0
# 3     B    NaN      NaN     _7     22.0
# 4     C    NaN      NaN     _8     23.0
# 5     X     _4     13.0    NaN      NaN

⚠️ 注意事项与最佳实践

列名后缀必须明确：务必通过 suffixes=('_1', '_2') 区分来源列，避免列名冲突；
排序不可省略：sort_values('class') 保证同类集中、阅读友好；如需进一步按序号排序，可追加 .sort_values(['class', 'key_1'])（需保留 key 列）；
空值处理：结果中自然出现 NaN 表示某一方无对应序号项，符合预期；若需替换为占位符（如 '—'），可用 out.fillna({'item_1': '—', 'value_1': 0})；
性能提示：对于超大数据集，cumcount() 是向量化操作，效率远高于 apply(lambda x: ...)，可放心用于万级行规模；
扩展性：该模式可轻松扩展至 3+ 个 DataFrame，只需依次两两 merge 并统一 suffixes 即可。

此方法将“报表布局逻辑”前置到数据准备阶段，完美适配 Streamlit、Dash 或导出 Excel 等强调终端呈现效果的场景——让数据分析真正服务于业务洞察，而非被格式所困。