热图可视化：pheatmap与ComplexHeatmap

热图是表达数据可视化最常用的图表类型。pheatmap 提供三行代码出图的基础方案，ComplexHeatmap 则支持高级布局、行列注释和多图拼接，适合发表场景。本文覆盖两个 R 包的数据标准化、配色调色板、注释配置和导出选项。

实测环境：R 4.4.1，pheatmap 1.0.12，ComplexHeatmap 2.18.0，Debian 13。

1. 数据准备——生信热图的数据长什么样#

热图的输入本质就是一张数值矩阵。生信中最常见的场景：

1
# 模拟一个 RNA-seq 表达矩阵：100个基因 × 10个样本
2
set.seed(42)
3
expr_matrix <- matrix(
4
    rnorm(1000, mean = 5, sd = 2),
5
    nrow = 100,
6
    ncol = 10,
7
    dimnames = list(
8
        paste0("Gene", 1:100),
9
        paste0("Sample", 1:10)
10
    )
11
)
12

13
# 人为制造一些差异（让热图有层次感）
14
expr_matrix[1:30, 1:5] <- expr_matrix[1:30, 1:5] + 3   # 前30个基因在前5个样本高表达
15
expr_matrix[71:100, 6:10] <- expr_matrix[71:100, 6:10] + 3  # 后30个基因在后5个样本高表达
16

17
head(expr_matrix[, 1:5])

真实场景中这个矩阵来自 DESeq2 的 normalized counts、limma 的差异基因列表、或者 WGCNA 的模块表达值。几行代码就能从 DESeq2 提取：

1
# 从 DESeq2 对象提取标准化表达矩阵
2
# dds <- DESeqDataSetFromMatrix(...)
3
# dds <- DESeq(dds)
4
# vsd <- vst(dds, blind = FALSE)
5
# expr_matrix <- assay(vsd)

2. pheatmap——三行代码出热图#

1
library(pheatmap)
2

3
# 最简单的热图
4
pheatmap(expr_matrix)

就这么简单。但默认参数出来的图有这些问题：基因名太多挤成一团、颜色默认红蓝不太友好、没做行标准化看不出相对差异。

2.1 加上标准化和聚类#

1
pheatmap(expr_matrix,
2
    scale = "row",              # 按行做 Z-score 标准化
3
    cluster_rows = TRUE,        # 行聚类
4
    cluster_cols = TRUE,        # 列聚类
5
    show_rownames = FALSE,      # 基因太多，不显示名字
6
    show_colnames = TRUE,
7
    main = "RNA-seq Expression Heatmap"
8
)

scale = "row" 是生信热图最关键的一个参数。表达式原始值的量级差异很大（基因A表达量 0.5，基因B表达量 5000），不标准化的话热图只能看到少数高表达基因，其他全是暗色。

Z-score 的公式：

$z_{ij} = \frac{x_{ij} - \mu_i}{\sigma_i}$

其中 $\mu_i$ 是基因 $i$ 在所有样本中的均值， $\sigma_i$ 是标准差。标准化后每个基因的均值 = 0，标准差 = 1，不同基因之间就”可比”了。

2.2 配色——告别红蓝默认色#

红蓝配色在色盲群体中难以区分，而且生信文献里几乎没人用。主流选择：

1
# 白-橙-红（表达量热图）
2
pheatmap(expr_matrix,
3
    scale = "row",
4
    color = colorRampPalette(c("white", "orange", "red"))(100),
5
    show_rownames = FALSE,
6
    main = "White-Orange-Red"
7
)
8

9
# 蓝-白-红（差异热图，白=不变，蓝=下调，红=上调）
10
pheatmap(expr_matrix,
11
    scale = "row",
12
    color = colorRampPalette(c("navy", "white", "firebrick3"))(100),
13
    show_rownames = FALSE,
14
    main = "Blue-White-Red (common in papers)"
15
)
16

17
# viridis 配色（色盲友好，越来越流行）
18
library(viridis)
19
pheatmap(expr_matrix,
20
    scale = "row",
21
    color = viridis(100),
22
    show_rownames = FALSE,
23
    main = "Viridis (colorblind-friendly)"
24
)

colorRampPalette 生成 100 个渐变色阶，越多越平滑。我一般杂志投哪个就用哪个配色，投 Nature 系列可以用 viridis，投 Cell 系列蓝白红更常见。

2.3 添加注释——这张图里最加分的部分#

纯热图只告诉你”这些基因在这些样本里高表达”，加上注释后可以同时展示样本分组、临床信息、突变状态等。

1
# 样本注释（列注释）
2
annotation_col <- data.frame(
3
    Group = factor(rep(c("Control", "Treatment"), each = 5)),
4
    Batch = factor(rep(c("Batch1", "Batch2"), times = 5)),
5
    row.names = paste0("Sample", 1:10)
6
)
7

8
# 基因注释（行注释，比如标记哪些是差异基因）
9
annotation_row <- data.frame(
10
    GeneClass = factor(c(
11
        rep("Oncogene", 30),
12
        rep("Tumor Suppressor", 30),
13
        rep("Other", 40)
14
    )),
15
    row.names = paste0("Gene", 1:100)
16
)
17

18
# 注释配色
19
ann_colors <- list(
20
    Group = c(Control = "#4DBBD5", Treatment = "#E64B35"),
21
    Batch = c(Batch1 = "#00A087", Batch2 = "#7E6148"),
22
    GeneClass = c(Oncogene = "#DC0000", `Tumor Suppressor` = "#3C5488", Other = "#8491B4")
23
)
24

25
pheatmap(expr_matrix,
26
    scale = "row",
27
    color = colorRampPalette(c("navy", "white", "firebrick3"))(100),
28
    annotation_col = annotation_col,
29
    annotation_row = annotation_row,
30
    annotation_colors = ann_colors,
31
    show_rownames = FALSE,
32
    main = "Expression Heatmap with Annotations",
33
    cutree_rows = 3,              # 把行聚类切成3个模块
34
    cutree_cols = 2               # 把列聚类切成2组
35
)

cutree_rows 和 cutree_cols 会自动在热图上画出聚类分割线——审稿人看到这条线就知道你做了聚类。

2.4 保存图片#

1
# png 格式
2
png("heatmap.png", width = 8, height = 10, units = "in", res = 300)
3
pheatmap(expr_matrix, scale = "row", show_rownames = FALSE)
4
dev.off()
5

6
# pdf 格式（矢量，适合投稿）
7
pdf("heatmap.pdf", width = 8, height = 10)
8
pheatmap(expr_matrix, scale = "row", show_rownames = FALSE)
9
dev.off()
10

11
# tiff 格式（部分期刊要求）
12
tiff("heatmap.tiff", width = 8, height = 10, units = "in", res = 300)
13
pheatmap(expr_matrix, scale = "row", show_rownames = FALSE)
14
dev.off()

注意 pheatmap 的输出是 grid 对象，不能直接用 ggsave。用基础的 png()/pdf()/tiff() + dev.off() 即可。

3. ComplexHeatmap——进阶玩家的选择#

pheatmap 能应付 80% 的场景，剩下的 20%——比如拼多列热图、自定义图例位置、oncoprint 等——需要 ComplexHeatmap。我一般简单探索用 pheatmap，要发表的图用 ComplexHeatmap。

3.1 基础用法#

1
library(ComplexHeatmap)
2
library(circlize)  # ComplexHeatmap 依赖 circlize 做配色
3

4
Heatmap(expr_matrix,
5
    name = "Expression",              # 图例标题
6
    col = colorRamp2(c(-2, 0, 2), c("navy", "white", "firebrick3")),
7
    row_names_gp = gpar(fontsize = 6),
8
    column_names_gp = gpar(fontsize = 8),
9
    show_row_names = FALSE,
10
    cluster_rows = TRUE,
11
    cluster_columns = TRUE
12
)

colorRamp2 比 colorRampPalette 更精确——你指定断点和对应的颜色，它自动插值。对于 Z-score 标准化数据，c(-2, 0, 2) 覆盖了约 95% 的数据范围。

3.2 添加注释——ComplexHeatmap 的方式#

1
# 列注释
2
column_ha <- HeatmapAnnotation(
3
    Group = annotation_col$Group,
4
    Batch = annotation_col$Batch,
5
    col = list(
6
        Group = c("Control" = "#4DBBD5", "Treatment" = "#E64B35"),
7
        Batch = c("Batch1" = "#00A087", "Batch2" = "#7E6148")
8
    ),
9
    annotation_legend_param = list(
10
        Group = list(title = "Group"),
11
        Batch = list(title = "Batch")
12
    )
13
)
14

15
# 行注释
16
row_ha <- rowAnnotation(
17
    GeneClass = annotation_row$GeneClass,
18
    col = list(GeneClass = c(
19
        "Oncogene" = "#DC0000",
20
        "Tumor Suppressor" = "#3C5488",
21
        "Other" = "#8491B4"
22
    ))
23
)
24

25
Heatmap(expr_matrix,
26
    name = "Z-score",
27
    col = colorRamp2(c(-2, 0, 2), c("navy", "white", "firebrick3")),
28
    top_annotation = column_ha,
29
    right_annotation = row_ha,
30
    show_row_names = FALSE,
31
    column_title = "RNA-seq Expression Heatmap",
32
    column_title_gp = gpar(fontsize = 14, fontface = "bold"),
33
    row_km = 3,                    # k-means 分成3个基因模块
34
    column_km = 2                  # 样本分成2组
35
)

ComplexHeatmap 把注释对象化——HeatmapAnnotation 管列注释，rowAnnotation 管行注释，逻辑清晰但代码量确实比 pheatmap 多。

3.3 拼图——ComplexHeatmap 的杀手锏#

多组数据并排展示是 ComplexHeatmap 最强的地方：

1
# 假设你有三个独立的表达矩阵（不同组织或不同处理）
2
set.seed(123)
3
mat1 <- matrix(rnorm(500, 5, 2), 50, 10)
4
mat2 <- matrix(rnorm(500, 5, 2), 50, 10)
5
mat3 <- matrix(rnorm(500, 5, 2), 50, 10)
6

7
rownames(mat1) <- rownames(mat2) <- rownames(mat3) <- paste0("Gene", 1:50)
8

9
# 分别画三张热图然后用 + 拼起来
10
ht1 <- Heatmap(mat1, name = "Tissue1", col = colorRamp2(c(-2,0,2), c("navy","white","red")),
11
               show_row_names = FALSE, column_title = "Normal")
12
ht2 <- Heatmap(mat2, name = "Tissue2", col = colorRamp2(c(-2,0,2), c("navy","white","red")),
13
               show_row_names = FALSE, column_title = "Tumor")
14
ht3 <- Heatmap(mat3, name = "Tissue3", col = colorRamp2(c(-2,0,2), c("navy","white","red")),
15
               show_row_names = FALSE, column_title = "Metastasis")
16

17
# 横向拼接
18
ht1 + ht2 + ht3
19

20
# 保存
21
pdf("multi_heatmap.pdf", width = 15, height = 8)
22
draw(ht1 + ht2 + ht3)
23
dev.off()

这个功能在需要展示”同一批基因在不同条件下”的表达模式时特别有用。你还可以用 row_order 让三张热图的基因顺序保持一致。

4. 踩坑记录#

坑1：pheatmap 报错 “margins too large”#

症状：基因名/样本名太多，R 报 figure margins too large。

解决：

1
# 方法1：调小字体
2
pheatmap(expr_matrix, fontsize_row = 4, fontsize_col = 6)
3

4
# 方法2：不显示行名
5
pheatmap(expr_matrix, show_rownames = FALSE)
6

7
# 方法3：增大画布（在 png/pdf 前设置）
8
pdf("heatmap.pdf", width = 20, height = 30)
9
pheatmap(expr_matrix)
10
dev.off()

坑2：scale=“row” 遇到全是相同值的行#

如果某基因在所有样本中表达量完全一样，标准差 = 0，scale("row") 会算出 NaN，热图里的该行是一片灰色。

1
# 排查
2
row_sds <- apply(expr_matrix, 1, sd)
3
table(row_sds == 0)
4

5
# 处理：过滤掉恒定基因，或给标准差加个极小值
6
expr_filtered <- expr_matrix[row_sds > 0.01, ]

实际数据中完全恒定的基因很少见（除非是 spike-in），但低表达基因近似恒定值的蛮多。

坑3：pheatmap 和 ComplexHeatmap 的行列顺序不一致#

两个包的聚类算法参数默认值不同，pheatmap 默认 clustering_method = "complete"，ComplexHeatmap 可以自定义。如果先画了 pheatmap 探索数据，再用 ComplexHeatmap 出图，聚类结果可能不一样。

1
# 统一聚类方法
2
Heatmap(expr_matrix, clustering_method_rows = "complete", clustering_method_columns = "complete")

坑4：ComplexHeatmap 图例标题不显示#

ComplexHeatmap 的图例标题 name 参数和 HeatmapAnnotation 里的 title 是两个东西。如果图例没标题，检查：

1
# Heatmap 的 name 必须设
2
Heatmap(expr_matrix, name = "Expression")  # 正确
3

4
# HeatmapAnnotation 里每个注释单独设 title
5
HeatmapAnnotation(
6
    Group = ...,
7
    annotation_legend_param = list(Group = list(title = "Sample Group"))
8
)

坑5：colorRamp2 颜色看起来不对#

colorRamp2 的颜色插值是线性的，但如果中间断点不对称，颜色过渡会偏：

1
# 不对称断点导致白色不在中间
2
colorRamp2(c(-3, 0, 1), c("blue", "white", "red"))
3
# 白-红区间只有1个单位，蓝-白有3个单位
4

5
# 尽量设对称断点
6
colorRamp2(c(-2, 0, 2), c("blue", "white", "red"))

坑6：中文标签在 PDF 里变成方框#

生信文章虽然以英文为主，但如果你要给国内报告画中文标签：

1
# PDF 里显示中文需要额外指定字体
2
library(showtext)
3
showtext_auto()
4
font_add("SimHei", "/usr/share/fonts/truetype/simhei.ttf")  # 黑体
5

6
# 然后在 Heatmap 里指定
7
Heatmap(expr_matrix,
8
    column_title = "基因表达热图",
9
    column_title_gp = gpar(fontfamily = "SimHei"),
10
    ...
11
)

5. 小结#

需求	推荐工具	代码量	灵活性
快速探索数据	pheatmap	3行	★★☆
加注释出图	pheatmap	15行	★★★
复杂排版拼图	ComplexHeatmap	30行+	★★★★★
发表级单图	两者都可	—	—
oncoprint/UpSet	ComplexHeatmap	—	★★★★★

我的习惯：探索数据时在 RStudio 里用 pheatmap 快速预览，确定分组和配色方案后，用 ComplexHeatmap 出最终版。colorRamp2 + HeatmapAnnotation 的组合基本能满足 95% 的生信热图需求。

配色小抄：

表达量热图：白→橙→红，或 viridis
差异分析热图：蓝→白→红
相关性热图：白→粉→深红
甲基化热图：蓝→黄→红

本文于 2025-09-14 在 Debian 13 + R 4.4.1 上实测完成。pheatmap 1.0.12，ComplexHeatmap 2.18.0。所有代码可直接复制运行。