如何正确将 Pandas DataFrame 转换为用于列重命名的一维字典

`pd.dataframe.to_dict()` 默认生成嵌套字典（按列为键），而列重命名需要的是 `{‘旧列名’: ‘新列名’}` 形式的扁平映射字典；应改用 `series.to_dict()`，即先通过 `set_index(col)[target_series]` 提取 series 再转换。

在使用 pandas 进行数据清洗时，常需根据映射表批量重命名 DataFrame 的列名。一个典型场景是：你有一个包含原始变量名（如 ‘B01001_001E’）和对应语义标签（如 ‘Total’）的参考表 cen_columns，目标是将 census_age 的列名替换为可读性更强的标签。

但若误用 DataFrame.to_dict()，会导致结构不匹配：

# ❌ 错误做法：返回嵌套字典 cen_columns = cen_columns[['VARIABLE','LABEL_CLEAN']].set_index("VARIABLE").to_dict() # 结果：{'LABEL_CLEAN': {'B01001_001E': 'Total', 'B01001_002E': 'Male', ...}}

该结果是一个以列名为键、以 {index: value} 为值的嵌套字典，无法直接用于 df.rename(columns=…) 或 Series.map() —— 因为 rename() 要求传入形如 {‘旧名’: ‘新名’} 的一维映射字典。

✅ 正确做法是先构造一个 Series，再调用 .to_dict()：

# ✅ 正确：提取单列 Series 后转字典 mapper = cen_columns.set_index("VARIABLE")["LABEL_CLEAN"].to_dict() # 结果：{'B01001_001E': 'Total', 'B01001_002E': 'Male', ...}  # 然后安全地重命名 census_age.rename(columns=mapper, inplace=True) # 或等价写法（推荐链式调用，避免 inplace） census_age = census_age.rename(columns=mapper)

? 补充说明：

• cen_columns.set_index(“VARIABLE”)[“LABEL_CLEAN”] 返回的是 pd.Series，其索引为 ‘VARIABLE’ 值，值为 ‘LABEL_CLEAN’ 内容；
• Series.to_dict() 天然生成 index → value 的扁平映射，完美契合 rename(columns=…) 的输入要求；
• 若参考表含重复 VARIABLE 值，.set_index() 会引发警告或覆盖，建议提前校验：cen_columns[‘VARIABLE’].is_unique；
• 替代方案 dict(zip(…)) 虽可行，但不如 Series.to_dict() 明确语义且支持自动处理缺失/重复索引逻辑。

总结：牢记 DataFrame → 嵌套字典，Series → 扁平字典。当目标是构建列名映射时，务必确保中间对象是 Series，而非 DataFrame。