seaborn heatmap输入必须为二维结构，如DataFrame或numpy 2D array；一维数据、Series等需转为二维，绘图后须用Axes对象精细调整标签、字体、数值显示及保存参数。
heatmap 函数输入必须是二维结构，不是 DataFrame 就得是 numpy 2D array
Seaborn 的 heatmap 不接受一维数据、字典、嵌套列表（非矩形）、Pandas Series 或三维以上数组。常见错误是传入 df.groupby(['x', 'y']).size() 这类结果——它返回的是 Series，得用 .unstack() 转成二维表，否则会报 ValueError: Input data must be 2D。
实操建议：
- 确认数据形状：用
data.shape检查是否为 (N, M)；若为 (N,)，先reshape或用pivot_table - DataFrame 直接传入即可，但列和索引应为类别型或数值型，避免混入时间戳或对象列（会触发
TypeError: unhashable type） - 如果原始是长格式（如三列：x, y, value），优先用
df.pivot(index='x', columns='y', values='value')，比手动unstack更稳
颜色映射（cmap）选错会导致关键差异被“洗白”
默认 cmap='viridis' 对连续型数值尚可，但对计数类热力图（如频次、占比）容易让低值区域全灰、高值区域过曝。比如展示用户点击分布时，cmap='Blues' 或 cmap='YlGnBu' 更直观；若含负值（如相关系数矩阵），必须用发散色盘，例如 cmap='RdBu_r'（注意加 _r 反转方向，使正相关为红、负相关为蓝）。
容易踩的坑：
立即学习“Python免费学习笔记（深入）”；
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 用
cmap='jet'—— 已被 Matplotlib 弃用，且人眼难分辨中间段色差 - 没设
vmin/vmax—— 当数据含异常值时，其余格子全挤在浅色区间，看不出梯度 - 忽略
center参数 —— 对以 0 为中心的数据（如残差、z-score），设center=0才能对称映射
坐标轴标签重叠、文字太小、数字不显示，本质是绘图后没干预 Axes
heatmap 返回一个 matplotlib.axes.Axes 对象，所有样式调整必须在其上操作，不能依赖函数参数“一步到位”。比如中文乱码、字体太小、刻度旋转，都得调用 ax.set_xticklabels() 或 plt.xticks() 等后续方法。
实操建议：
- 中文支持：提前运行
plt.rcParams['font.sans-serif'] = ['SimHei', 'Arial Unicode MS']，并加plt.rcParams['axes.unicode_minus'] = False - 旋转 x 轴标签：用
ax.set_xticklabels(ax.get_xticklabels(), rotation=30)（别用xticks(rotation=30)，它可能失效） - 显示数值：加参数
annot=True，再用fmt='.1f'控制小数位；若数据是整数频次，用fmt='d'避免显示 .0
保存图像时 dpi 和 bbox_inches 决定能否完整导出
直接 plt.savefig('hmap.png') 经常切掉顶部标题或右侧 colorbar，尤其当启用了 annot=True 或长标签时。根本原因是 matplotlib 默认裁剪范围未包含所有元素。
正确做法：
- 始终加
bbox_inches='tight'，它会自动收缩画布到内容边界 - 需要高清图（如论文插图）：设
dpi=300，但注意figsize得同步放大，否则文字糊成一片；推荐先设plt.figure(figsize=(10, 8))，再调用heatmap - colorbar 太窄？用
cbar_kws={'shrink': 0.8}调整其高度比例
热力图真正的麻烦不在画出来，而在让每一格的数值、标签、颜色对比都经得起细看——尤其是当别人拿你的图去汇报或嵌入文档时，缩放后仍要可读。
