Heatmap and Annotation Legends

Author: Zuguang Gu ( z.gu@dkfz.de )

Date: 2015-10-14

Legends for all heatmaps and row annotations are drawn together and legends for all column annotations are drawn together. The legends for heatmaps and legends for annotations are put in independent viewports.

library(ComplexHeatmap)
library(circlize)

set.seed(123)
mat = matrix(rnorm(80, 2), 8, 10)
mat = rbind(mat, matrix(rnorm(40, -2), 4, 10))
rownames(mat) = paste0("R", 1:12)
colnames(mat) = paste0("C", 1:10)

ha_column = HeatmapAnnotation(df = data.frame(type1 = c(rep("a", 5), rep("b", 5))), 
    col = list(type1 = c("a" =  "red", "b" = "blue")))
ha_row = rowAnnotation(df = data.frame(type2 = c(rep("A", 6), rep("B", 6))), 
    col = list(type2 = c("A" =  "green", "B" = "orange")), width = unit(1, "cm"))

ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", top_annotation = ha_column)
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2")
ht_list = ht1 + ht2 + ha_row

draw(ht_list)

plot of chunk legend_default

Side of legends can be set by heatmap_legend_side and annotation_legend_side.

draw(ht_list, heatmap_legend_side = "left", annotation_legend_side = "bottom")

plot of chunk legend_side

show_heatmap_legend and show_annotation_legend set visibility of legends.

draw(ht_list, show_heatmap_legend = FALSE, show_annotation_legend = FALSE)

plot of chunk legend_show

You can choose to only show some of the heatmap legends by setting show_heatmap_legend to a logical value when constructing single heatmaps. Also HeatmapAnnotation() (or the shortcut function columnAnnotation() and rowAnnotation()) provides show_legend argument to control visibility of annotation legends.

ha_column = HeatmapAnnotation(df = data.frame(type1 = c(rep("a", 5), rep("b", 5))), 
    col = list(type1 = c("a" =  "red", "b" = "blue")), show_legend = FALSE)
ha_row = rowAnnotation(df = data.frame(type2 = c(rep("A", 6), rep("B", 6))), 
    col = list(type2 = c("A" =  "green", "B" = "orange")), show_legend = FALSE, width = unit(1, "cm"))

ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", top_annotation = ha_column)
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2", show_heatmap_legend = FALSE)
ht1 + ht2 + ha_row

plot of chunk legend_show_part

ComplexHeatmap only generates legends for heatmaps and simple annotations. Self-defined legends can be passed by heatmap_legend_list and annotation_legend_list as a list of grob objects.

grid package provides legendGrob() to construct a legend grob with certain style but styles are still limited. For advanced users, they can construct a legend grob totally from ground by frameGrob() and packGrob().

ha = HeatmapAnnotation(points = anno_points(rnorm(10)))
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2", top_annotation = ha, show_heatmap_legend = FALSE)
lgd = legendGrob(c("dots"), pch = 16)
draw(ht1 + ht2, annotation_legend_list = list(lgd))

plot of chunk self_defined_annotation_legend

Parameters for making the legend can be set by heatmap_legend_param (for heatmap) or annotation_legend_param (for annotations). The parameters that can be set are as follows:

title: title of the legend
title_gp: graphic parameters for the legend title
color_bar: style of the color bar, i.e. continuous or discrete
grid_height: height of the small grid in the color bar, only works for discrete color bar
grid_width: width of the color bar
grid_border: border of the color bar
at: break values shown on the legend
labels: labels which correspond to the breaks values
labels_gp: graphic parameters for legend labels

df = data.frame(type = c(rep("a", 5), rep("b", 5)))
ha = HeatmapAnnotation(df = df, col = list(type = c("a" =  "red", "b" = "blue")),
    annotation_legend_param = list(type = list(title = "TYPE", title_gp = gpar(fontsize = 14), 
                                               labels_gp = gpar(fontsize = 8))))
ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", top_annotation = ha)
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2", 
    heatmap_legend_param = list(title = "Heatmap2", title_gp = gpar(fontsize = 8), labels_gp = gpar(fontsize = 14)))
ht1 + ht2

plot of chunk heatmap_list_advanced

You can specify break values and break labels (both for character values and numeric values) by at and labels in corresponding heatmap_legend_param and annotation_legend_param.

ha = HeatmapAnnotation(df = df, col = list(type = c("a" =  "red", "b" = "blue")),
    annotation_legend_param = list(type = list(title = "TYPE", title_gp = gpar(fontsize = 14), 
        labels_gp = gpar(fontsize = 8), at = c("a", "b"), labels = c("A", "B"))))
ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", top_annotation = ha,
    heatmap_legend_param = list(at = c(-3, 0, 3), labels = c("-three", "zero", "+three")))
ht1 + ht2

plot of chunk self_define_heatmap_legend

If you don't like the default discrete color bar for legends, you can specify color_bar to continuous. For the simple annotation which contains continuous values, color_bar can also be set to continuous.

ha = HeatmapAnnotation(df = data.frame(value = runif(10)), 
    col = list(value = colorRamp2(c(0, 1), c("white", "blue"))), 
    annotation_legend_param = list(color_bar = "continuous"))
Heatmap(mat, name = "ht1", top_annotation = ha, heatmap_legend_param = list(color_bar = "continuous"))

plot of chunk unnamed-chunk-1

If you want to change default settings for all heatmaps/annotations, you can set it globally by ht_global_opt().

ht_global_opt(heatmap_legend_title_gp = gpar(fontsize = 16), annotation_legend_labels_gp = gpar(fontface = "italic"))
ha = HeatmapAnnotation(df = data.frame(value = runif(10)), 
    col = list(value = colorRamp2(c(0, 1), c("white", "blue"))), 
    annotation_legend_param = list(color_bar = "continuous"))
ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", top_annotation = ha)
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2", heatmap_legend_param = list(title_gp = gpar(fontsize = 8)))
ht1 + ht2

plot of chunk unnamed-chunk-2

ht_global_opt(RESET = TRUE)

Session info

sessionInfo()

## R version 3.2.2 (2015-08-14)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 14.04.3 LTS
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C               LC_TIME=en_US.UTF-8       
##  [4] LC_COLLATE=C               LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                  LC_ADDRESS=C              
## [10] LC_TELEPHONE=C             LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
##  [1] stats4    parallel  grid      stats     graphics  grDevices utils     datasets  methods  
## [10] base     
## 
## other attached packages:
##  [1] dendextend_1.1.0     dendsort_0.3.2       cluster_2.0.3        HilbertCurve_1.0.0  
##  [5] GenomicRanges_1.22.0 GenomeInfoDb_1.6.0   IRanges_2.4.0        S4Vectors_0.8.0     
##  [9] BiocGenerics_0.16.0  circlize_0.3.1       ComplexHeatmap_1.6.0 knitr_1.11          
## [13] markdown_0.7.7      
## 
## loaded via a namespace (and not attached):
##  [1] whisker_0.3-2       XVector_0.10.0      magrittr_1.5        zlibbioc_1.16.0    
##  [5] lattice_0.20-33     colorspace_1.2-6    rjson_0.2.15        stringr_1.0.0      
##  [9] tools_3.2.2         png_0.1-7           RColorBrewer_1.1-2  formatR_1.2.1      
## [13] HilbertVis_1.28.0   GlobalOptions_0.0.8 shape_1.4.2         evaluate_0.8       
## [17] mime_0.4            stringi_0.5-5       GetoptLong_0.1.0