热图注释是热图的重要组成部分，它显示与热图中的行或列相关联的附加信息，也是一个看起来高水平热图的主要原因。 ComplexHeatmap包为设置注释和定义新的注释图形提供了非常灵活的支持。注释可以放在热图的四个侧面，由top_annotation，bottom_annotation， left_annotation和right_annotation参数组成。
接下来我们将对不同的注释函数anno_*()进行学习和测试，如空注释anno_empty()、块注释anno_block()、图像注释anno_image()、点注释anno_points()、线注释anno_lines()、条形图注释anno_barplot()、箱线图注释anno_boxplot()、直方图注释anno_histogram()、密度注释anno_density()等注释方法。
四个参数的值应该在HeatmapAnnotation类中并且由HeatmapAnnotation()函数构造，如果是行注释则由rowAnnotation()函数构造。(rowAnnotation()只是一个与HeatmapAnnotation(..., which = "row")相同的辅助函数) 。
我们还是用上一篇的测试数据为例：
column_ha = HeatmapAnnotation(foo1 = runif(24), bar1 = anno_barplot(runif(24)))
row_ha = rowAnnotation(foo2 = runif(18), bar2 = anno_barplot(runif(18)))
Heatmap(mat, name = "mat", top_annotation = column_ha, right_annotation = row_ha)
将热图注释指定为底部注释和左侧注释。
Heatmap(mat, name = "mat", bottom_annotation = column_ha, left_annotation = row_ha)
在上面的例子中，column_ha和row_ha都有两个注释，其中 foo1和foo2是数字向量，bar1和bar2是条形图。类似向量的注解在这里称为“简单注释”，条形图注解称为“复杂注释”，注释必须定义为名称=值对（例如 foo = ...）。
另外，值得注意的是，热图注释也可以独立于热图。它们可以通过+（水平连接）或%v%（垂直连接）到热图列表，类似于ggplot的图层概念，一层层的望上加。
Heatmap(...) + rowAnnotation() + ...
Heatmap(...) %v% HeatmapAnnotation(...) + ...
下面我们学习各种注释的类型。
1. 简单注释
所谓的“简单注释”是最常用的注释样式，它是类似热图或类似网格的图形，其中使用颜色映射到注释值。要生成一个简单的注释，您只需简单地将一个特定的名称注释向量放入HeatmapAnnotation()中。
下面2个例子就是2个简单的离散型变量的简单注释。
ha = HeatmapAnnotation(foo = 1:10)
ha = HeatmapAnnotation(bar = sample(letters[1:3], 10, replace = TRUE))
如果未指定颜色，则随机生成颜色。col设置注释的颜色，col需要设置命名列表。
library(circlize)
col_fun = colorRamp2(c(0, 5, 10), c("blue", "white", "red"))
ha = HeatmapAnnotation(foo = 1:10, col = list(foo = col_fun))
ha = HeatmapAnnotation(bar = sample(letters[1:3], 10, replace = TRUE),
col = list(bar = c("a" = "red", "b" = "green", "c" = "blue")))
如果您指定多个向量，则会有多个注释（foo和bar）。col中的值将用于构建简单注释的图例。例如下面的例子就包含了foo和bar两个注释，颜色里面就会有
ha = HeatmapAnnotation(
foo = 1:10,
bar = sample(letters[1:3], 10, replace = TRUE),
col = list(foo = col_fun,
bar = c("a" = "red", "b" = "green", "c" = "blue")
)
)
gp 主要控制网格边界的图形参数。
ha = HeatmapAnnotation(
foo = 1:10,
bar = sample(letters[1:3], 10, replace = TRUE),
col = list(foo = col_fun,
bar = c("a" = "red", "b" = "green", "c" = "blue")
),
gp = gpar(col = "black")
)
简单注释的高度由simple_anno_size 参数控制。由于所有单个注释具有相同的高度，因此 的值 simple_anno_size是单个unit值。注意 width，height，annotation_width和annotation_height，是用来调整的完整heamtap注释（这总是混合几种注释）的宽度/高度。
ha = HeatmapAnnotation(
foo = cbind(a = 1:10, b = 10:1),
bar = sample(letters[1:3], 10, replace = TRUE),
col = list(foo = col_fun,
bar = c("a" = "red", "b" = "green", "c" = "blue")
),
simple_anno_size = unit(1, "cm")
)
2. 简单注释作为函数
HeatmapAnnotation()通过将注释设置为函数来支持“复杂注释”。annotation 函数定义了如何在热图中的列或行对应的某个位置绘制图形。ComplexHeatmap包中预定义了很多注释函数 。
对于anno_*()形式的所有注释函数，如果在HeatmapAnnotation()或rowAnnotation()中指定 ，则不需要明确地做任何anno_*()事情来判断它是应该绘制在行上还是列上。anno_*()将会自动检测是行注释环境还是列注释环境。
上一节中的简单注解是由anno_simple()注解函数内部构造的 。直接使用anno_simple() 不会自动为最终绘图生成图例，但是，它可以为更多的注释图形提供更大的灵活性，这个功能允许在注释网格上添加更多符号。anno_simple()允许在注释网格顶部添加“点”或单字母符号。pch，pt_gp和pt_size控制点的设置。pch的值可以是具有可能NA值的向量。
ha = HeatmapAnnotation(foo = anno_simple(1:10, pch = 1,
pt_gp = gpar(col = "red"), pt_size = unit(1:10, "mm")))
ha = HeatmapAnnotation(foo = anno_simple(1:10, pch = 1:10))
如果 anno_simple()的值是矩阵，pch也可以使用。 pch的长度应该与矩阵的行数或列数甚至矩阵的长度相同（矩阵的长度是矩阵中所有数据点的长度）。
ha = HeatmapAnnotation(foo = anno_simple(cbind(1:10, 10:1), pch = 1:2))
下面我们绘制一个简单的例子，加入一个常见的pvalue的信息。
pvalue = 10^-runif(24, min = 0, max = 3)
is_sig = pvalue < 0.01
pch = rep("*", 10)
pch[!is_sig] = NA
pvalue_col_fun = colorRamp2(c(0, 2, 3), c("green", "white", "red"))
#生成一个pvalue的注释信息
ha = HeatmapAnnotation(
pvalue = anno_simple(-log10(pvalue), col = pvalue_col_fun, pch = pch),
annotation_name_side = "left")
由于我们使用了函数，所以不会自动产生legend信息，我们需要自己加入pvalue的legend信息。
lgd_pvalue = Legend(title = "p-value", col_fun = pvalue_col_fun, at = c(0, 1, 2, 3),
labels = c("1", "0.1", "0.01", "0.001"))
lgd_sig = Legend(pch = "*", type = "points", labels = "< 0.01")
draw(ht, annotation_legend_list = list(lgd_pvalue, lgd_sig))
3. 块注释
块注释更像是一个颜色块，它在热图的行或列被拆分时标识组。
Heatmap(mat, name = "mat",
top_annotation = HeatmapAnnotation(foo = anno_block(gp = gpar(fill = 2:4))),
column_km = 3)
更复杂一点的，行和列都加上标签，以及对标签的文字进行控制。
Heatmap(mat,
top_annotation = HeatmapAnnotation(foo = anno_block(gp = gpar(fill = 2:4),
labels = c("group1", "group2", "group3"),
labels_gp = gpar(col = "white", fontsize = 10))),
column_km = 3,
left_annotation = rowAnnotation(foo = anno_block(gp = gpar(fill = 2:4),
labels = c("group1", "group2", "group3"),
labels_gp = gpar(col = "white", fontsize = 10))),
row_km = 3)
4. 点注释
点注释anno_points()为实现显示数据点在列表中的分布。数据点对象x可以是单个向量或矩阵。如果它是一个矩阵，图形属性设置（例如pch，size和gp）可以关联到矩阵的列。再次注意，如果x是矩阵，则行x 对应于热图矩阵中的列。
ha = HeatmapAnnotation(foo = anno_points(runif(10)))
ha = HeatmapAnnotation(foo = anno_points(matrix(runif(20), nc = 2),
pch = 1:2, gp = gpar(col = 2:3)))
5. 线注释
anno_lines()通过段列表连接数据点。和点注释类似，就是点之间连成了线。与 anno_points()类似，数据变量可以是数值向量：
ha = HeatmapAnnotation(foo = anno_lines(runif(10)))
ha = HeatmapAnnotation(foo = anno_lines(cbind(c(1:5, 1:5), c(5:1, 5:1)),
gp = gpar(col = 2:3), add_points = TRUE, pt_gp = gpar(col = 5:6), pch = c(1, 16)))
#如上图所示，可以通过设置将点添加到线中add_points = TRUE。也通过设置smooth = TRUE可以添加平滑线（by loess()）而不是原始线，但应谨慎使用，因为热图中列的顺序用作拟合的“x值”，并且仅当您认为拟合反对重新排序的顺序是有道理的。
6. 条形图注释
数据点可以表示为条形图。 anno_barplot()的一些参数：如ylim，axis，axis_param和 anno_points()是一样的。
ha = HeatmapAnnotation(foo = anno_barplot(1:10))
条行图的宽度由 bar_width控制。它是热图中单元格宽度的相对值。图形参数由gp控制。
ha = HeatmapAnnotation(foo = anno_barplot(1:10, gp = gpar(fill = 1:10)))
可以通过baseline选择条形的基线。
ha = HeatmapAnnotation(foo = anno_barplot(seq(-5, 5), baseline = 0))
当时矩阵的时候，就是堆积柱形图了。
ha = HeatmapAnnotation(foo = anno_barplot(cbind(1:10, 10:1),
gp = gpar(fill = 2:3, col = 2:3)))
7. 箱线图注释
Boxplot注解以及后面介绍的注解函数更适合小矩阵。不适合就有多列矩阵的列注释。
对于anno_boxplot()，输入数据变量应该是矩阵或列表。如果 x是矩阵，如果是列注释，则箱线图的统计量按列计算，如果是行注释，则按行计算。
m = matrix(rnorm(100), 10)
ha = HeatmapAnnotation(foo = anno_boxplot(m, height = unit(4, "cm")))
图形参数和前面一样由gp控制。框的宽度由box_width控制。outline控制是否显示离群点。
8. 直方图注释
作为直方图的注释更适合作为行注释。数据变量的设置与anno_boxplot()相同，可以是矩阵或列表。由anno_histogram实现。
与anno_boxplot()类似，输入数据变量应该是矩阵或列表。如果 x是矩阵，如果是列注释，则直方图按列计算，如果是行注释，则直方图按行计算。
m = matrix(rnorm(1000), nc = 100)
ha = rowAnnotation(foo = anno_histogram(m))
直方图的中断次数由n_breaks控制。颜色由gp控制。
9. 密度曲线注释
与直方图注释类似，anno_density()将分布显示为拟合曲线。
ha = rowAnnotation(foo = anno_density(m))
