1 Introduction

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

1.1 General design

A single heatmap is composed by the heatmap body and the heatmap components. The heatmap body can be split by rows and columns. The heatmap components are titles, dendrograms, row/column names/labels and heatmap annotations, which are put on the four sides of the heamap body. The heatmap components are reordered or split according to the heatmap body.

A heatmap list is concatenation of a list of heatmaps and heatmap annotations. Surrounding the heatmap list, there are global-level titles and legends.

One important thing for the heatmap list is that rows for all heatmaps and annotations are all adjusted so that the same row in all heatmaps and annotations corresponds to a same feature.

The heatmaps and annotations (now it is column annotation) can also be arranged vertically.

And the heatmap list can also be split by rows and by columns.

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 row/column annotations.
• HeatmapList class: a list of heatmaps and heatmap annotations.
• HeatmapAnnotation class: defines a list of row annotations and column annotations. The heatmap annotations can be components of heatmap, also they can be independent as heatmaps.

There are also several internal classes:

• SingleAnnotation class: defines a single row annotation or column annotation. The HeatmapAnnotation object contains a list of SingleAnnotation objects.
• ColorMapping class: mapping from values to colors. The color mappings of the main matrix and the annotations are controlled by ColorMapping class.
• AnnotationFunction class: constructs user-defined annotations. This is the base of creating user-defined annotation graphics.

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

1.2 A brief description of following chapters

• A Single Heatmap

This chapter describes the configurations of a single heatmap.

• Heatmap Annotations

This chapter describes the concept of the heatmap annotation and demonstrates how to make simple annotations as well as complex annotations. Also, the chapter explains the difference between column annotations and row annotations.

• A List of Heatmaps

This chapter describes how to concatenate a list of heatmaps and annotations and how adjustment is applied to keep the correspondence of the heatmaps.

• Legends

This chapter describes how to configurate the heatmap legends and annotation legends, also how to create self-defined legends.

• Heatmap Decoration

This chapter describes methods to add more self-defined graphics to the heatmaps after the heatmaps are generated.

• OncoPrint

This chapter describes how to make oncoPrints and how to integrate other functionalities from ComplexHeatmap to oncoPrints.

• UpSet plot

This chapter describes how to make enhanced UpSet plots.

• Other High-level Plots

This chapter describes functions implemented in ComplexHeatmap for specific use, e.g. visualizing distributions.

• Integrate with other packages

This chapter describes how other packages are integrated with ComplexHeatmap. Currently, we demonstrate the two packages of gridtext and pheatmap.

• Interactive heatmap

This chapter describes how to make heatmaps interactive.

• More Examples

More simulated and real-world examples are demonstrated in this chapter.