Complex heatmaps are efficient to visualize associations between different sources of data sets and reveal potential structures. Here the ComplexHeatmap package provides a highly flexible way to arrange multiple heatmaps and supports self-defined annotation graphics.

Zuguang Gu, Roland Eils and Matthias Schlesner, Complex heatmaps reveal patterns and correlations in multidimensional genomic data, Bioinformatics, 2016

Generally, a heatmap list contains several heatmaps and row annotations.

Surrounding the heatmap list, there are legends for heatmaps and annotations, also there are titles which are placed on the four sides of the heatmap list. And for each heatmap, there are also different components surrounding the heatmap body.

The ComplexHeatmap package is implemented in an object-oriented way. To describe a heatmap list, there are following classes:

• Heatmap class: a single heatmap containing heatmap body, row/column names, titles, dendrograms and column annotations.
• HeatmapList class: a list of heatmaps and row annotations.
• HeatmapAnnotation class: defines a list of row annotations and column annotations.

There are also several internal classes:

• SingleAnnotation class: defines a single row annotation or column annotation.
• ColorMapping class: mapping from values to colors.

ComplexHeatmap is implemented under grid system, so users should know basic grid functionality to get full use of the package.

ComplexHeatmap is available on Bioconductor, you can intall it by:

source("https://bioconductor.org/biocLite.R")
biocLite("ComplexHeatmap")

If you want the latest version, install it directly from GitHub:

library(devtools)
install_github("jokergoo/ComplexHeatmap")

Make a single heatmap:

Heatmap(mat, ...)

A single Heatmap with column annotations:

ha = HeatmapAnnotation(df = anno1, anno_fun = anno2, ...)
Heatmap(mat, ..., top_annotation = ha)

Make a list of heatmaps:

Heatmap(mat1, ...) + Heatmap(mat2, ...)

Make a list of heatmaps and row annotations:

ha = HeatmapAnnotation(df = anno1, anno_fun = anno2, ..., which = "row")
Heatmap(mat1, ...) + Heatmap(mat2, ...) + ha

ComplexHeatmap can be used as a base package to build other packages which focus On specific applications. E.g. EnrichedHeatmap package uses ComplexHeatmap as base to make heatmaps which visualize the enrichment of genomic signals to specific target regions.

There are several vignettes in the package. Each vignette focuses on a specific topic. Following lists the general topics discussed in these vignettes:

1. Making a Single Heatmap

This vignette introduces the basic configuration for making a single heatmap. Similar as other
R functions/packages, the basic usage is quite similar, but there are several unique features
for **ComplexHeamtap** package.
- Works both for numeric matrix and character matrix
- For numeric matrix which contains continuous values, the package allows a color mapping function
  which can give more accurate colors and be robust to outliers.
- Highly flexible for clustering. You can define the distance method for clustering by:
      * a pre-defined distance such as "euclidean" or "pearson"
      * a self-defined function which calculates distance from a matrix.
      * a self-defined function which calculates distance from two vectors
    
    You can define the clustering method by:
      * a clustering function such as `diana()` from **cluster** package
      * a `hclust` or `dendrogram` object.
- `NA` is allowed for clustering and heatmap visualization.
- Dendrogram and dimension names can be put on any side of the heatmap.
- Rows on the heatmap can be split by `cutree`, by `kmeans` or by a data frame which contains 
  different levels that split the heatmap.
- The heatmap body itself can be completely self-defined.

2. Making a List of Heatmaps

This vignette introduces how to concatenate a list of heatmaps and how adjustment is applied to keep
the correspondence of the heatmaps.

3. Heatmap Annotations

This vignette introduces the concept of the heatmap annotation and demonstrate how to make simple annotations
as well as complex annotations. Also, the vignette explains the difference between column annotations
and row annotations.

4. Heatmap and Annotation Legends

This vignette introduces how to configurate the heatmap legend and annotation legend, also
how to add self-defined legends.

5. Heatmap Decoration

This vignette introduces methods to add more self-defined graphics to the heatmaps after the heatmaps
are generated.

6. Interactive with Heatmaps

How to select a region in the heatmap to retrieve the sub-matrix.

7. OncoPrint

How to make an oncoPrint.

8. Examples

More simulated and real-world examples are shown in this vignette.

The examples visualizes correlation between methylation and expression, as well as other annotation information (data are randomly generated). In the heatmap, each row corresponds to a differentially methylated regions (DMRs). From left to right, heatmaps are:

1. methylation for each DMRs in samples.
2. direction of the methylation (one column heatmap), i.e. is methylation hyper in tumor or hypo?
3. expression for the genes that are associated with corresponding DMRs (e.g. closest gene).
4. signiciance for the correlation between methylation and expression (-log10(p-value)).
5. type of genes, i.e. is the gene a protein coding gene or a lincRNA?
6. annotation to gene models, i.e. is the DMR located in the intragenic region of the corresponding gene or the DMR is intergenic?
7. distance from the DMR to the TSS of the corresponding gene.
8. overlapping between DMRs and enhancers (Color shows how much the DMR is covered by the enhancers).

OncoPrint visualize multiple genomic alteration events through a heatmap. From verion 1.3.0, ComplexHeatmap package provides a new oncoPrint() function. By this function, users can define their own graphics which correspond to differnet alteration events. Also the function additionally add barplots on two sides of the heatmap which tell number of different alterations in patients or samples.

With general functionality of ComplexHeamtap, you can add more heatmaps / row annotations to the oncoPrint, even split the oncoPrint to enphasize sub groups.

You can use mouse to select a region on the heatmap, it will return row index and column index which correspond to the selected region.

GPL (>= 2)