Author: Zuguang Gu ( z.gu@dkfz.de )
Date: 2015-10-14
A list of heatmaps can improve visualization of the correspondence between multiple data sources. In this vignette, we will discuss configurations for making a list of heatmaps and you can see more real-world examples in the Examples vignette.
You can arrange more than one heatmaps on the plot from left to right. Actually, one single heatmap is just a special case of the heatmap list of length one.
Heatmap() is actually a class constructor function for a single heatmap. If more than one heatmaps
are to be combined, users can append one heatmap to the other by + operator.
library(ComplexHeatmap)
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)
ht1 = Heatmap(mat, name = "ht1")
ht2 = Heatmap(mat, name = "ht2")
class(ht1)
## [1] "Heatmap"
## attr(,"package")
## [1] "ComplexHeatmap"
class(ht2)
## [1] "Heatmap"
## attr(,"package")
## [1] "ComplexHeatmap"
ht1 + ht2
Under default mode, dendrograms from the second heatmap will be removed and row orders will be same as the first one.
The returned value of addition of two heatmaps is a HeatmapList object. Directly calling ht_list object
will call draw() method with default settings. With explicitly calling draw() method, you can have more controls
on the legend and titles.
ht_list = ht1 + ht2
class(ht_list)
## [1] "HeatmapList"
## attr(,"package")
## [1] "ComplexHeatmap"
You can append any number of heatmaps to the heatmap list. Also you can append a heatmap list to a heatmap list.
ht1 + ht1 + ht1
ht1 + ht_list
ht_list + ht1
ht_list + ht_list
NULL can be added to the heatmap list. It would be convinient when users want to construct a heatmap list through a for loop.
ht_list = NULL
for(s in sth) {
ht_list = ht_list + Heatmap(...)
}
A heatmap list also has titles which are independent to the heatmap titles.
ht1 = Heatmap(mat, name = "ht1", row_title = "Heatmap 1", column_title = "Heatmap 1")
ht2 = Heatmap(mat, name = "ht2", row_title = "Heatmap 2", column_title = "Heatmap 2")
ht_list = ht1 + ht2
draw(ht_list, row_title = "Two heatmaps, row title", row_title_gp = gpar(col = "red"),
column_title = "Two heatmaps, column title", column_title_side = "bottom")
The gaps between heatmaps can be set by gap argument with a unit object.
draw(ht_list, gap = unit(1, "cm"))
draw(ht_list + ht_list, gap = unit(c(3, 6, 9, 0), "mm"))
The width for some (not all) heatmaps can be set to a fixed width.
ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1")
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2", width = unit(5, "cm"))
ht1 + ht2
or the width can be set as relative values. Please not in this case, width for all heatmaps
should be set (relative width and fixed width can be mixed).
ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", width = 2)
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2", width = 1)
ht1 + ht2
There are some automatic adjustment if more than one heatmaps are plotted. There should be a main heatmap which by default is the first one. Some settings for the remaining heatmaps will be modified to the settings in the main heatmap. The adjustment are:
The main heatmap can be specified by main_heatmap argument. The value can be a numeric index or the name of the heatmap
(of course, you need to set the heatmap name when you create the Heatmap object).
ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", km = 2)
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2")
ht1 + ht2
# note we changed the order of `ht1` and `ht2`
draw(ht2 + ht1)
# here although `ht1` is the second heatmap, we specify `ht1` to be
# the main heatmap by explicitely setting `main_heatmap` argument
draw(ht2 + ht1, main_heatmap = "ht1")
If there is no row clustering in the main heatmap, all other heatmaps have no row clustering neither.
ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1", cluster_rows = FALSE)
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2")
ht1 + ht2
ht_global_opt() can set graphic parameters for dimension names and titles as global settings.
ht_global_opt(heatmap_row_names_gp = gpar(fontface = "italic"),
heatmap_column_names_gp = gpar(fontsize = 14))
ht1 = Heatmap(mat, name = "ht1", column_title = "Heatmap 1")
ht2 = Heatmap(mat, name = "ht2", column_title = "Heatmap 2")
ht1 + ht2
ht_global_opt(RESET = TRUE)
Following are global settings supported by ht_global_opt(). By this function, you can also control settings
for the legends.
names(ht_global_opt())
## [1] "heatmap_row_names_gp" "heatmap_column_names_gp" "heatmap_row_title_gp"
## [4] "heatmap_column_title_gp" "heatmap_legend_title_gp" "heatmap_legend_labels_gp"
## [7] "heatmap_legend_grid_height" "heatmap_legend_grid_width" "heatmap_legend_grid_border"
## [10] "annotation_legend_title_gp" "annotation_legend_labels_gp" "annotation_legend_grid_height"
## [13] "annotation_legend_grid_width" "annotation_legend_grid_border"
row_order, column_order, row_dend and column_dend can be used to retrieve corresponding information from
the heatmaps. The usage is straightforward by following example:
ht_list = ht1 + ht2
row_order(ht_list)
## [[1]]
## [1] 12 11 9 10 1 6 4 5 8 3 2 7
column_order(ht_list)
## $ht1
## [1] 1 7 8 2 3 4 9 5 6 10
##
## $ht2
## [1] 1 7 8 2 3 4 9 5 6 10
row_dend(ht_list)
## [[1]]
## 'dendrogram' with 2 branches and 12 members total, at height 15.87414
column_dend(ht_list)
## $ht1
## 'dendrogram' with 2 branches and 10 members total, at height 7.858248
##
## $ht2
## 'dendrogram' with 2 branches and 10 members total, at height 7.858248
If ht_list has not been drawn yet, calling these four functions would be a little bit slow if the matrix are huge.
But if ht_list is already drawn which means clustering is already applied to the matrix, it will be fast to retrieve
these information.
ht_list = draw(ht1 + ht2)
row_order(ht_list)
column_order(ht_list)
row_dend(ht_list)
column_dend(ht_list)
Row annotations can also be reordered and split according to the main heatmap, please see Heatmap Annotation for more explanations.
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