R ComplexHeatmap绘制热图时行名rownames无法显示问题求助

排查优先级（按故障出现概率从高到低） #

• 全局热图参数残留覆盖：此前运行代码时调用过ht_opt()修改过全局默认参数，或在当前Heatmap参数中隐性设置了行名字号为0、行名颜色为透明，即使显式写了show_row_names=TRUE也不会显示行名。
• 绘图区域边距不足：行聚类树、行注释模块占比过高，或热图整体宽度设置过大，没有给行名预留足够的绘图空间，行名会被直接裁剪，调整row_names_side参数不会解决空间不足的问题。
• 输入矩阵行名属性异常：矩阵经过转置、子集筛选、合并等操作后，行名属性丢失、变为空字符串、存在大量重复值，会被ComplexHeatmap判定为无效行名自动隐藏。
• 包冲突或版本bug：同时加载pheatmap、iheatmapr等其他热图包时可能出现函数命名冲突，2.14.0之后的几个ComplexHeatmap开发版也存在行名渲染的适配bug，行切片过多时也可能触发行名被挤到绘图区外的问题。

可直接落地的修复步骤 #

1. 重置全局参数，强制指定行名渲染属性
   绘图前先清空所有残留的全局热图配置，不要依赖默认参数，显式给出行名的字号、颜色设置：

   # 重置全局热图参数
   ht_opt(RESET = TRUE)
   # 先关闭所有注释、聚类树做最小化测试
   Heatmap(
       mat = 热图矩阵,
       show_row_names = TRUE,
       row_names_side = "left",
       row_names_gp = gpar(fontsize = 10, col = "black"), # 强制指定字号、颜色，避免透明/0号字
       cluster_rows = FALSE, # 测试时先关闭行聚类
       left_annotation = NULL,
       right_annotation = NULL,
       split = NULL # 测试时先关闭行切片
   )
   

   如果这一步能正常显示行名，再逐步加回聚类、注释、切片参数，定位是哪个模块挤占了空间。

2. 手动调整边距预留行名空间
   如果最小化测试依然不显示行名，显式设置绘图内边距，给行名留出足够的绘制区域：

   Heatmap(
       mat = 热图矩阵,
       show_row_names = TRUE,
       row_names_side = "left",
       row_names_gp = gpar(fontsize = 10, col = "black"),
       padding = unit(c(1, 1, 1, 2), "cm") # 四个参数分别对应上、右、下、左边距，行名放左侧就把左边距调大
   )
   

3. 修复输入矩阵的行名属性
   不要依赖操作过程中自动保留的行名，绘图前强制重绑有效行名：

   # 提取原有行名转成字符串，处理重复值
   raw_rn <- rownames(热图矩阵)
   rownames(热图矩阵) <- make.unique(as.character(raw_rn))
   # 验证行名有效性，确认输出不是NULL、没有空值
   print(head(rownames(热图矩阵)))
   

4. 排除环境冲突与版本问题
   先重启R会话，不加载其他热图相关包，用内置测试数据集验证环境是否正常：

   # Rstudio中执行重启R
   .rs.restartR()
   # 仅加载ComplexHeatmap
   library(ComplexHeatmap)
   # 生成测试矩阵绘图
   test_mat <- matrix(rnorm(100), nrow = 10, dimnames = list(paste0("test_gene_", 1:10), paste0("sample_", 1:10)))
   Heatmap(test_mat, show_row_names = TRUE, row_names_side = "left")
   

   • 如果测试矩阵可以正常显示行名，说明故障来自你之前的代码环境污染或输入矩阵问题，回到前3步排查即可。
   • 如果测试矩阵也无法显示行名，卸载当前版本安装Bioconductor稳定版ComplexHeatmap即可。

内容的提问来源于stack exchange，提问作者PesKchan