热力图数据必须是二维结构，pandas DataFrame 最稳妥；需用 pivot 转宽格式并处理重复索引和缺失值；cmap 应按数据类型选择并显式设置 vmin/vmax；行列标签过长时优先降维抽样；annot 需控制精度与 NaN 对齐，并自定义文字颜色。
热力图数据必须是二维结构，pandas DataFrame 最稳妥
Seaborn 的 sns.heatmap() 本质只接受二维数组（如 numpy.ndarray）或带行列索引的 pandas.DataFrame。如果你原始数据是“宽表”（如用户-商品-评分），直接传入会报错 ValueError: data must be 2-dimensional。
常见错误是把含多列非数值字段的原始 DataFrame 直接塞进去——它不自动筛选数值列，也不帮你 pivot。
- 先用
df.pivot(index='user_id', columns='item_id', values='rating')转成宽格式；index 和 columns 必须是唯一组合，否则抛ValueError: Index contains duplicate entries - 如果原始数据含缺失组合（比如某用户没评过某商品），
pivot()会自动填NaN，这没问题——sns.heatmap()默认跳过NaN - 避免用
pd.crosstab()代替pivot()：它只能做频次统计，不能保留原始数值字段
颜色映射（cmap）选错会导致关键差异被淹没
默认的 cmap='viridis' 对连续型数值尚可，但对离散等级（如 1–5 分评分）或偏态分布（大量 0 + 少量高值）极易丢失对比度。
- 评分类数据优先试
cmap='RdYlBu_r'（红黄蓝反向，低分红、高分蓝）或cmap='Blues'（单色渐变，更强调高低） - 含大量零值的稀疏矩阵，加参数
center=0让 colormap 以 0 为中点，避免全图偏冷/偏暖 - 别依赖默认
vmin/vmax：显式设vmin=1, vmax=5可确保不同子图间颜色标尺一致，否则无法横向比较
行列标签太长时，字体缩放和旋转不是万能解
当 x 或 y 轴有上百个类别（如股票代码、时间戳），硬调 xticklabels 字体大小或 rotation 常导致标签重叠或截断，且影响 heatmap 单元格渲染比例。
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
立即学习“Python免费学习笔记（深入）”；
- 优先降维：用
df.index[::5]或df.sample(n=50).index抽样显示，比强行显示全部更有效 - 真要全显示？改用
plt.xticks(ticks=range(len(df.columns)), labels=df.columns, rotation=45, fontsize=6)—— 注意必须在sns.heatmap()后调用，且fontsize要压到 6–8 - 行标签（y-axis）别用
rotation：垂直文字渲染不可靠，改用plt.yticks(fontsize=7)配合紧凑布局
叠加数值标注（annot）时，浮点精度和遮挡是隐形坑
annot=True 看似方便，但默认显示全部小数位，密密麻麻的 3.245678 不仅难读，还会因字体大小和单元格尺寸不匹配导致文字溢出或重叠。
- 用
annot=df.round(1).values替代annot=True，自己控制精度 - 若数据含
NaN，annot数组也必须对应位置为''或np.nan，否则报TypeError: unsupported format string passed to numpy.ndarray.__format__ - 文字颜色别依赖默认：加
annot_kws={'color': 'white', 'size': 8}，尤其深色 cmap 下黑字几乎看不见
真正麻烦的从来不是画出来，而是让别人一眼看懂——轴标签是否可读、颜色是否反映业务意义、缺失值是否被合理对待，这些细节在快速绘图时最容易被跳过。
