热力图数据必须是二维结构，需用pivot()或pivot_table()将宽表转为行列明确的二维矩阵，处理重复索引、缺失值、中文标签、配色方案、标签密度及数值标注精度等问题。
热力图数据必须是二维结构，不是DataFrame就能直接画
Seaborn 的 sns.heatmap() 只接受二维数组或类似结构（如 DataFrame、numpy 2D array），它不支持直接传入带多列原始观测数据的宽表或长表。常见错误是把原始 CSV 直接丢进去，结果报错 ValueError: Input z must be 2D 或热图只显示一列/一行。
典型场景：你有一份含 year、region、sales 三列的数据，想以年份为行、区域为列、销售额为颜色值——这需要先用 pivot() 聚合成二维矩阵：
df_pivot = df.pivot(index='year', columns='region', values='sales')
注意三点：
-
pivot()要求index和columns组合唯一，否则报ValueError: Index contains duplicate entries；此时改用pivot_table()并指定聚合函数，例如aggfunc='mean' - 缺失值会显示为空白或默认色块，可用
na_values参数控制，或提前用fill_value=0填充 - 如果列名或索引含中文/特殊字符，
sns.heatmap()默认能渲染，但若字体缺失可能显示方框，加plt.rcParams['font.sans-serif'] = ['SimHei']解决
颜色映射（cmap）选错会导致关键差异被掩盖
默认 cmap='viridis' 是连续型配色，适合数值跨度大、分布较均匀的数据；但如果你的数据集中在某一小段（比如 95–100 分的学生成绩），默认配色会让所有格子看起来差不多，看不出高低差异。
立即学习“Python免费学习笔记（深入）”；
实操建议：
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 先用
df_pivot.describe()看数值范围和分布，再决定是否归一化或换 cmap - 对偏态数据，用
cmap='RdBu_r'或cmap='coolwarm'更易识别正负/高低对比 - 离散型数值（如等级 1–5）建议搭配
center=3+cmap='RdYlBu_r'，让中间值对应中性色 - 避免用
cmap='jet'（已弃用），人眼对其中黄绿过渡不敏感，易误判
标签重叠、字体过小是热力图最常被忽略的排版问题
默认情况下，sns.heatmap() 会把所有行名、列名都打出来，当行列数超过 10，x/y 轴标签必然挤成一团，根本看不清。
解决方法不是“调大 figure size”，而是针对性控制：
- 用
xticklabels=False或yticklabels=False关闭不需要的轴标签 - 用
xticklabels=10（数字）表示每 10 个列显示一个标签；或传入列表如xticklabels=['Q1','Q2','Q3','Q4'] - 调整字体大小统一用
annot_kws={'size': 8}（数值标注）和fontsize=9（坐标轴）参数，别混用plt.xticks()后续设置，容易失效 - 若需旋转标签，用
plt.xticks(rotation=45)，但仅在plt.show()前调用才生效
添加数值标注（annot）时要注意数据类型和精度
开启 annot=True 很方便，但常出现“每个格子标出 12 位小数”或“标出 nan”这种干扰信息。
正确做法：
- 确保传入
sns.heatmap()的数据是数值型（df_pivot.values.dtype应为 float/int），否则annot=True会静默失败 - 用
fmt='.1f'控制小数位数，fmt='d'用于整数，fmt='.2%'用于百分比（前提是数据已除以 100） - 若部分单元格是 NaN，
annot=True默认标出nan字符串，可先用df_pivot.fillna('')或df_pivot.round(2).fillna('')预处理 - 数值太长（如 123456789）会撑开格子，配合
annot_kws={'ha': 'center'}居中对齐更稳妥
热力图真正难的从来不是画出来，而是让别人一眼看懂——行列顺序、空值处理、数值精度、颜色断点，漏掉任意一环，图就变成装饰画。
