Table of Contents

Introduction to ComplexHeatmap package

Author: Zuguang Gu ( )

Date: 2018-10-30

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.

General design

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

plot of chunk design

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:

There are also several internal classes:

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


There are several vignettes in the package. Each vignette focuses on one 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.

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

In the supplementaries of the ComplexHeatmap paper, there are four comprehensive examples which are applied on real-world high-throughput datasets. The examples can be found here.

Also my blog has some examples and tips for making better complex heatmaps.