<!--
%\VignetteEngine{knitr}
%\VignetteIndexEntry{3. Making a list of Heatmaps}
-->

Making A List of Heatmaps
========================================

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

**Date**: `r Sys.Date()`

-------------------------------------------------------------

```{r global_settings, echo = FALSE, message = FALSE}
library(markdown)
options(markdown.HTML.options = c(options('markdown.HTML.options')[[1]], "toc"))

library(knitr)
knitr::opts_chunk$set(
    error = FALSE,
    tidy  = FALSE,
    message = FALSE,
    fig.align = "center",
    fig.width = 5,
    fig.height = 5)
options(markdown.HTML.stylesheet = "custom.css")

options(width = 100)
```

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**](s9.examples.html) vignette as well as [in the 
supplementaries](http://jokergoo.github.io/supplementary/ComplexHeatmap-supplementary1-4/index.html) of [the ComplexHeatmap paper](http://bioinformatics.oxfordjournals.org/content/early/2016/05/20/bioinformatics.btw313.abstract).

## Heatmap concatenation

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.

```{r heatmap_list_default, fig.width = 10}
library(ComplexHeatmap)

mat1 = matrix(rnorm(80, 2), 8, 10)
mat1 = rbind(mat1, matrix(rnorm(40, -2), 4, 10))
rownames(mat1) = paste0("R", 1:12)
colnames(mat1) = paste0("C", 1:10)

mat2 = matrix(rnorm(60, 2), 6, 10)
mat2 = rbind(mat2, matrix(rnorm(60, -2), 6, 10))
rownames(mat2) = paste0("R", 1:12)
colnames(mat2) = paste0("C", 1:10)

ht1 = Heatmap(mat1, name = "ht1")
ht2 = Heatmap(mat2, name = "ht2")
class(ht1)
class(ht2)

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
e.g. on the legend and titles.

```{r}
ht_list = ht1 + ht2
class(ht_list)
```

You can append any number of heatmaps to the heatmap list. Also you can append a heatmap list to a heatmap list.

```{r, eval = FALSE}
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.

```{r, eval = FALSE}
ht_list = NULL
for(s in sth) {
    ht_list = ht_list + Heatmap(...)
}
```

## Titles

A heatmap list also has titles which are independent to the heatmap titles.

```{r heatmap_list_title, fig.width = 10}
ht1 = Heatmap(mat1, name = "ht1", row_title = "Heatmap 1", column_title = "Heatmap 1")
ht2 = Heatmap(mat2, 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")
```

## Gaps between heatmaps

The gaps between heatmaps can be set by `gap` argument with a `unit` object.

```{r heatmap_list_gap, fig.width = 10, fig.keep = "all"}
draw(ht_list, gap = unit(1, "cm"))
draw(ht_list + ht_list, gap = unit(c(3, 6, 9, 0), "mm"))
```

## Size of heatmaps

The width for some (not all) heatmaps can be set to a fixed width.

```{r heatmap_list_size, fig.width = 10, fig.keep = "all"}
ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1")
ht2 = Heatmap(mat2, 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).

```{r heatmap_list_relative_size, fig.width = 10, fig.keep = "all"}
ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1", width = 2)
ht2 = Heatmap(mat2, name = "ht2", column_title = "Heatmap 2", width = 1)
ht1 + ht2
```

## Auto adjustment

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:

- row clusters are removed.
- row titles are removed.
- if the main heatmap is split by rows, all remaining heatmaps will also be split by same levels as the main one.

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).

```{r heatmap_list_auto_adjust, fig.width = 10, fig.keep = "all"}
ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1", km = 2)
ht2 = Heatmap(mat2, 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.

```{r heatmap_list_auto_adjust_no_row_cluster, fig.width = 10}
ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1", cluster_rows = FALSE)
ht2 = Heatmap(mat2, name = "ht2", column_title = "Heatmap 2")
ht1 + ht2
```

## Change graphic parameters simultaneously

`ht_global_opt()` can set graphic parameters for dimension names and titles as global settings.

```{r, fig.width = 10}
ht_global_opt(heatmap_row_names_gp = gpar(fontface = "italic"), 
	          heatmap_column_names_gp = gpar(fontsize = 14))
ht1 = Heatmap(mat1, name = "ht1", column_title = "Heatmap 1")
ht2 = Heatmap(mat2, 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.

```{r}
names(ht_global_opt())
```

## Retrieve orders and dendrograms

`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:

```{r}
ht_list = ht1 + ht2
row_order(ht_list)
column_order(ht_list)
row_dend(ht_list)
column_dend(ht_list)
```

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.

```{r, eval = FALSE}
ht_list = draw(ht1 + ht2)
row_order(ht_list)
column_order(ht_list)
row_dend(ht_list)
column_dend(ht_list)
```

## Heatmap list with row annotations

Row annotations can be added to the heatmap list, 
please see [**Heatmap Annotation**](s4.heatmap_annotation.html) for more explanations.

## Modify row orders/clustering in main heatmap

From version 1.11.1, settings for row order/clustering for the main heatmap can be directly set
in `draw()` method. This makes it convinient to switch main heatmaps without modifying settings in individual
heatmaps. Actually settings specified in `draw()` will overwrite corresponding settings in the main heatmap.

```{r, fig.width = 8}
split = rep(c("a", "b"), each = 6)
ht_list = Heatmap(mat1, name = "mat1", cluster_rows = FALSE, column_title = "mat1") + 
          Heatmap(mat2, name = "mat2", cluster_rows = FALSE, column_title = "mat2")
draw(ht_list, main_heatmap = "mat1", split = split)
draw(ht_list, main_heatmap = "mat2", km = 2, cluster_rows = TRUE)
draw(ht_list, cluster_rows = TRUE, main_heatmap = "mat1", show_row_dend =TRUE)
draw(ht_list, cluster_rows = TRUE, main_heatmap = "mat2", show_row_dend =TRUE)
```

## Session info

```{r}
sessionInfo()
```
