14 文本注释

使用 anno_text() 来添加文本注释

ha <- rowAnnotation(  foo = anno_text(    month.name,    location = 1,    just = "center",    rot = 45,    gp = gpar(      fontsize = 5:17    )  ))

location 和 just 会根据注释的位置自动计算，如果注释放置在右边，则文本会左对齐，反之，在左边，右对齐

根据所有文本会自动计算 width/height 的值，一般不需要手动设置

ha <- rowAnnotation(  foo = anno_text(    month.name,    location = 0.5,    just = "center",    gp = gpar(      fill = rep(rainbow(10)[2:5], each = 4),      col = "black",      border = "black"    ),    width = max_text_width(month.name) * 1.2  ))

可以使用 gridtext 包绘制更复杂的文本

15. 标记注释

anno_mark（代替了被替换的 anno_link）用于标记某些行/列，并使用线条连接文本和对应的行/列

anno_mark() 至少需要两个参数，at 提供原始数据矩阵的索引，labels 为相应的文本标记

mat <- matrix(rnorm(1000), nrow = 100)rownames(mat) <- 1:100ha <- rowAnnotation(  foo = anno_mark(    at = c(1:4, 20, 60, 97:100),     labels = month.name[1:10])  )Heatmap(  mat, name = "mat",   cluster_rows = FALSE,   right_annotation = ha,  row_names_side = "left",   row_names_gp = gpar(fontsize = 4)  )

anno_summary() 用于对只有一行或一列的热图提供统计汇总注释

如果数据为离散型向量，将绘制条形图

v <- sample(letters[1:2], 50, replace = TRUE)split <- sample(letters[1:2], 50, replace = TRUE)ha <- HeatmapAnnotation(  summary = anno_summary(height = unit(4, "cm")))Heatmap(  v, name = "mat",   col = c("a" = "red", "b" = "blue"),  top_annotation = ha,   width = unit(2, "cm"),   row_split = split)

对于连续型向量将绘制箱线图

v <- rnorm(50)ha <- HeatmapAnnotation(  summary = anno_summary(    gp = gpar(fill = 3:4),    height = unit(4, "cm")    ))Heatmap(  v, name = "mat",   top_annotation = ha,   width = unit(2, "cm"),   row_split = split)

我们通常不会单独绘制只包含一列的热图，而是会与其他热图绘制在一起

比如，我们在基因表达矩阵的边上，绘制一个 lncRNA 或 MiRNA 的表达热图

# 设置热图配色col_fun <- colorRamp2(  c(-2, 0, 2),   c("#8c510a", "white", "#01665e"))# 绘制主热图exp <- matrix(rnorm(50*10), nrow = 50)main <- Heatmap(  exp, name = "main_matrix",  col = col_fun  )# 绘制一列离散型热图v <- sample(letters[1:2], 50, replace = TRUE)lnc <- Heatmap(  v, name = "mat1",   # 设置离散型颜色  col = structure(c("#f46d43", "#66bd63"), name = letters[1:2]),  top_annotation = HeatmapAnnotation(    summary = anno_summary(      height = unit(3, "cm")    )  ),   width = unit(1, "cm"),  )# 绘制一列连续型热图v <- rnorm(50)mi <- Heatmap(  v, name = "mat2",   col = col_fun,  top_annotation = HeatmapAnnotation(    summary = anno_summary(      gp = gpar(fill = 2:3),       height = unit(3, "cm"))  ),   width = unit(1, "cm")  )# 按列添加多个热图ht_list <- main + lnc + misplit <- sample(letters[1:2], 50, replace = TRUE)draw(ht_list,      row_split = split,      ht_gap = unit(5, "mm"),      heatmap_legend_list = list(lgd_boxplot)     )

anno_mark() 用于将某些行/列连接到文本标签，anno_zoom() 则用于将行列子集连接到一个绘图区域，并可在该区域绘制自定义图形。可以理解为从热图矩阵中拿出部分子集来绘制一个任意的图形

例如，我们可以为每个分组绘制一个箱线图

# 设置热图配色col_fun <- colorRamp2(  c(-2, 0, 2),   c("#8c510a", "white", "#01665e"))# 生成表达谱exp <- matrix(rnorm(100*10), nrow = 100)# 设置分组group <- sample(letters[1:3], 100,                 replace = TRUE,                 prob = c(1, 5, 10)                )panel_fun <- function(index, nm) {  # 添加绘图 viewport  pushViewport(viewport(xscale = range(exp), yscale = c(0, 2)))  # 绘制区域外侧框线  grid.rect()  grid.xaxis(gp = gpar(fontsize = 8))  # 添加箱线图  grid.boxplot(    exp[index, ], pos = 1,     gp = gpar(fill = index + 6),    direction = "horizontal"    )  popViewport()}Heatmap(  exp, name = "exp",   col = col_fun,  row_split = group,  height = unit(10, "cm"),  width = unit(12, "cm"),  right_annotation = rowAnnotation(    foo = anno_zoom(      align_to = group,      which = "row",      panel_fun = panel_fun,      size = unit(2, "cm"),      gap = unit(1, "cm"),      width = unit(4, "cm")    ))  )

anno_zoom() 函数的参数

align_to：定义了行或列的分组绘图区域。如果是索引列表，则其中每个向量为一组，如果为分类变量，则将根据 level 分组panel_fun：自定义的绘图函数。函数的第一个参数为 index，表示分组在矩阵中的索引，第二个参数为 nm，代表选择的热图区域的名称，该名称来自 align_to 的分类变量或 list 中的名称size：箱子的大小，可以是绝对值或相对值，相对于热图的宽度和高度gap：箱子的间隔

获取代码：

18. 多个注释18.1 常规设置

在前面的示例中，我们以键值对的方式在 HeatmapAnnotation() 函数中添加多个注释，还有一些参数用于控制多个注释，这些参数的值长度要与注释数目相同

不管是向量、矩阵或数据框数据，绘制简单注释都会自动添加图例，使用 show_legend 可以控制图例的显示

对于输入数据的不同，show_legend 的格式也有区别：

长度为简单注释数量的逻辑向量长度为所有注释的数量，对应于复杂注释的值将被忽略命名向量，控制简单注释的子集

例如

ha = HeatmapAnnotation(  foo = 1:10,   bar = cbind(1:10, 10:1),  pt = anno_points(1:10),  show_legend = c("bar" = FALSE))Heatmap(  matrix(rnorm(100), 10),   name = "mat",   top_annotation = ha  )

border 控制单个注释的外侧框线，show_annotation_name 控制注释名称的显示

ha <- HeatmapAnnotation(  foo = 1:10,   bar = cbind(1:10, 10:1),  pt = anno_points(1:10),  gp = gpar(col = "red"),  show_annotation_name = c(bar = FALSE),  border = c(foo = TRUE))

annotation_name_gp, annotation_name_offset, annotation_name_side 和 annotation_name_rot 用于控制注释名的样式属性和位置，后面三个可以被设置为命名向量。

当 annotation_name_offset 设置为命名向量时，值不需要 unit 函数设置，可以直接使用字符表示annotation_name_offset = c(foo = "1cm")

gap 参数用于设置两个注释的间隔，可以是单个值或向量

ha <- HeatmapAnnotation(  foo = 1:10,   bar = cbind(1:10, 10:1),  pt = anno_points(1:10),  gap = unit(2, "mm")  )

ha <- HeatmapAnnotation(  foo = 1:10,   bar = cbind(1:10, 10:1),  pt = anno_points(1:10),  gap = unit(c(2, 10), "mm")  )

height, width, annotation_height 和 annotation_width 用于控制复杂注释的大小，通常来说，简单注释不需要设置，会根据图形自动调整。

例如

# foo: 1cm, bar: 5mm, pt: 1cmha <- HeatmapAnnotation(  foo = cbind(1:10, 10:1),   bar = 1:10,  pt = anno_points(1:10)  )

当使用 height 参数设置注释的高度时，简单注释的高度不会改变，只会改变复杂注释的高度

# foo: 1cm, bar: 5mm, pt: 4.5cmha <- HeatmapAnnotation(  foo = cbind(1:10, 10:1),   bar = 1:10,  pt = anno_points(1:10),  height = unit(6, "cm")  )

simple_anno_size 控制所有简单注释的大小，全局简单注释的大小可以使用 ht_opt$simple_anno_size 设置

# foo: 2cm, bar:1cm, pt: 3cmha <- HeatmapAnnotation(  foo = cbind(1:10, 10:1),    bar = 1:10,  pt = anno_points(1:10),  simple_anno_size = unit(1, "cm"),   height = unit(6, "cm")  )

所有简单注释都被设置为 1cm

annotation_height 可以分别为每个注释设置高度

# foo: 1cm, bar: 2cm, pt: 3cmha <- HeatmapAnnotation(  foo = cbind(1:10, 10:1),   bar = 1:10,  pt = anno_points(1:10),  annotation_height = unit(1:3, "cm")  )

annotation_height 也可以设置为纯数值，会将其作为注释的相对比例值

# foo: 1cm, bar: 2cm, pt: 3cmha <- HeatmapAnnotation(  foo = cbind(1:10, 10:1),   bar = 1:10,  pt = anno_points(1:10),  annotation_height = 1:3,  height = unit(6, "cm")  )

annotation_height 也可以混合绝对值和相对值

# foo: 1.5cm, bar: 1.5cm, pt: 3cmha <- HeatmapAnnotation(  foo = cbind(1:10, 10:1),   bar = 1:10,  pt = anno_points(1:10),  annotation_height = unit(c(1, 1, 3), c("null", "null", "cm")),   height = unit(6, "cm"))

如果只有简单注释，设置 height 将不会有任何作用

# foo: 1cm, bar: 5mmha <- HeatmapAnnotation(  foo = cbind(1:10, 10:1),   bar = 1:10,  height = unit(6, "cm")  )

除非将 simple_anno_size_adjust 设置为 TRUE

ha <- HeatmapAnnotation(  foo = cbind(1:10, 10:1),   bar = 1:10,  simple_anno_size_adjust = TRUE,  height = unit(6, "cm")  )

有一些实用函数，可以对注释进行更灵活的操作，例如，对于如下注释

ha <- HeatmapAnnotation(  foo = 1:10,   bar = cbind(1:10, 10:1),  pt = anno_points(1:10)  )

计算注释的数量，观察值的数量

> draw(ha)> length(ha)[1] 3> nobs(ha)[1] 10

获取和设置注释的名称

> names(ha)[1] "foo" "bar" "pt" > names(ha) <- c("A", "B", "C")> names(ha)[1] "A" "B" "C"

如果两个 HeatmapAnnotation 对象具有相同的观测值且注释名称不同，可以连接起来

ha1 <- HeatmapAnnotation(  foo = 1:10,   bar = cbind(1:10, 10:1),  pt = anno_points(1:10)  )ha2 <- HeatmapAnnotation(  FOO = runif(10),   BAR = sample(c("a", "b"), 10, replace = TRUE),  PT = anno_points(rnorm(10))  )ha <- c(ha1, ha2)

> names(ha)[1] "foo" "bar" "pt"  "FOO" "BAR" "PT" 

可以对 HeatmapAnnotation 对象进行取子集操作，行对应为观察值，列对应注释名称

> ha_subset <- ha[1:5, c("foo", "PT")]> ha_subsetA HeatmapAnnotation object with 2 annotations  name: heatmap_annotation_154   position: column   items: 5   width: 1npc   height: 15.3514598035146mm   this object is subsetable  5.21733333333333mm extension on the left   6.75733333333333mm extension on the right  name   annotation_type color_mapping height  foo continuous vector        random    5mm   PT     anno_points()                 10mm

ComplexHeatmap 中的所有注释函数都是使用 AnnotationFunction 类来构造的

AnnotationFunction 类的重要部分是一个函数，该函数定义如何在与热图中的行或列相对应的特定位置处进行绘制图形

该函数包含三个参数：

index：对应于热图矩阵的行或列的索引，包含行或列重新排序后当前切片的行或列索引的列表k：代表当前热图块的索引n：代表所有热图块数目

后两个参数是可选的，注释函数会在每个切片中独立绘制。

var_import 参数用于存储该函数的额外参数

AnnotationFunction 的一个特性是可子集化，用于需要定义输入变量的拆分规则，包中自带了子集化规则函数 subset_gp(), subset_matrix_by_row() 和 subset_vector()，如果未指定，会根据输入对象的类型自动推断

例如，定义一个简单的注释函数

x <- 1:10anno1 <- AnnotationFunction(  fun = function(index, k, n) {    n = length(index)    # 根据索引长度分配 viewport 空间    pushViewport(viewport(xscale = c(0.5, n + 0.5), yscale = c(0, 10)))    grid.rect()    # 绘制散点    grid.points(1:n, x[index], default.units = "native")    if(k == 1) grid.yaxis()    popViewport()  },  # 传递函数的额外参数  var_import = list(x = x),  n = 10,  subsetable = TRUE,  height = unit(2, "cm"))

下面来使用它

m = rbind(1:10, 11:20)Heatmap(  m,   top_annotation = HeatmapAnnotation(foo = anno1)  )

应用于分割热图块

Heatmap(  m,   top_annotation = HeatmapAnnotation(foo = anno1),   column_split = rep(c("A", "B"), each = 5)  )

上面的函数可以改进，将数据变量放入内部

anno2 <- AnnotationFunction(    fun = function(index) {        x = 1:10        n = length(index)        pushViewport(viewport())        grid.points(1:n, x[index])        popViewport()    },    n = 10,    subsetable = TRUE)

最精简的方式是，自定义函数

anno3 <- AnnotationFunction(    fun = function(index) {        x = 1:10        n = length(index)        pushViewport(viewport())        grid.points(1:n, x[index])        popViewport()    })

其实，本节中介绍的所有 anno_*() 函数实际上并不是真正的注释函数，它们只是生成具有特定配置的注释函数的函数

事实上，ComplexHeatmap 已经提供了足够多的函数了，可以满足绝大部分的需求。实在没有的，也可以通过 anno_empty() 放置一个空白占位，然后使用 decorate_annotation() 函数快速添加自定义图形。