Pandas droplevel() 删除多级列索引教程

本文详解 `droplevel()` 在处理 `pd.read_html()` 解析出的多级表头时的正确用法，解决因误操作 `players[0]` 导致的 `AttributeError` 和 `KeyError`，并提供列索引降级、数据合并等完整实践步骤。

当你使用 pd.read_html() 从网页中解析表格时，Pandas 常会将具有嵌套结构（如带“主标题+子标题”的统计表）的 HTML 表格自动解析为 多级列索引（MultiIndex）。例如，一个“Standard Stats”表格可能生成形如 (‘Player’, ‘’), (‘Shooting’, ‘Dist’) 的双层列名。此时直接调用 .droplevel() 是合理的，但必须确保操作对象是 DataFrame.columns（即 Index 或 MultiIndex 类型），而非普通 Python 列表或错误索引的 DataFrame。

✅ 正确操作流程

首先明确：pd.read_html(...) 始终返回 list 类型，即使只匹配到一个表格，也需显式取 [0] 获取 DataFrame：

# ❌ 错误：players 是 list，list 没有 .columns 属性
players = pd.read_html(data.text, match="Standard Stats")
players.columns = players.columns.droplevel()  # AttributeError！

# ✅ 正确：先提取 DataFrame，再操作其 columns
players = pd.read_html(data.text, match="Standard Stats")[0]
players.columns = players.columns.droplevel(0)  # 显式指定 level=0（顶层）

? 注意：.droplevel() 默认降第一级（level=0），但建议显式传参增强可读性。若列索引有三层，可写 .droplevel([0, 1]) 或 .droplevel(0).droplevel(0)。

⚠️ 常见错误解析

• AttributeError: 'list' object has no attribute 'columns'
  根源：对 players（列表）直接调用 .columns。修复：务必先执行 players = players[0]。

• KeyError: 0（在 players[0] 时报错）
  根源：players 已是 DataFrame，此时 players[0] 被解释为按列名 0 查找——但列名通常为字符串（如 'Player'），导致 KeyError。删除该行即可：

  # ❌ 错误残留（在已赋值为 DataFrame 后还写 players[0]）
  players = pd.read_html(StringIO(data.text), match="Standard Stats")[0]
  players[0]  # → KeyError: 0
  
  # ✅ 正确：只需打印或后续处理
  print(players.head())  # 查看结果

? 合并多表时的列名对齐技巧

你提到需将 players 与 shooting 表按 "Player" 字段合并，却报 KeyError: 'Player'。这通常意味着：

1. 目标列名不存在：检查实际列名是否含空格、大小写差异或隐藏层级

   print(players.columns.tolist())  # 查看真实列名，如可能是 ('Player', '') 或 'Player Name'
   print(shooting.columns.tolist())

2. 多级列索引未清理：若 shooting 同样来自 read_html()，也需先降级：

   shooting = pd.read_html(data.text, match="Shooting Stats")[0]
   shooting.columns = shooting.columns.droplevel(0)  # 先清理列索引

3. 安全合并（推荐）：显式指定左右键，避免依赖列名直连：

   # 确保 players 和 shooting 都有 'Player' 列（且类型一致）
   team_data = players.merge(
       shooting[['Player', 'Dist']],    # 显式选取所需列
       on='Player',                      # 指定连接键
       how='left'                        # 推荐 left，保留 players 全量数据
   )

✅ 最终稳健代码模板

import pandas as pd
from io import StringIO

# 1. 解析并提取单个 DataFrame
players = pd.read_html(data.text, match="Standard Stats")[0]
shooting = pd.read_html(data.text, match="Shooting Stats")[0]

# 2. 清理多级列索引（关键！）
players.columns = players.columns.droplevel(0)
shooting.columns = shooting.columns.droplevel(0)

# 3. 可选：标准化列名（去除空格/统一大小写）
players.columns = players.columns.str.strip().str.title()
shooting.columns = shooting.columns.str.strip().str.title()

# 4. 合并（确保 'Player' 列存在且无缺失）
print("Players columns:", players.columns.tolist())
print("Shooting columns:", shooting.columns.tolist())

team_data = players.merge(
    shooting[['Player', 'Dist']],
    on='Player',
    how='left'
)

? 提示：使用 df.info() 和 df.columns.tolist() 是调试列索引问题最高效的手段。永远先验证数据结构，再执行 .droplevel() 或 .merge() —— 这能避免 90% 的 KeyError。

通过以上步骤，你不仅能正确移除冗余表头层级，还能构建健壮的数据整合流水线，为后续分析打下坚实基础。