ComplexHeatmap

Dependencies & Environment

Package-intrinsic requirements from the Bioconductor landing page — reproduce in any R environment.

• Version: 2.28.0 · Bioconductor: 3.23 · R: ≥ 4.6
• Imports: circlize, GetoptLong, colorspace, clue, RColorBrewer, GlobalOptions, png, digest, IRanges, matrixStats, foreach, doParallel, codetools
• Install: BiocManager::install("ComplexHeatmap")

When to Use

• Visualizing global patterns in matrices with a huge number of rows or columns.
• Arranging and concatenating multiple heatmaps vertically (using %v%) or horizontally (using +).
• Adding complex annotations (e.g., points, barplots) alongside heatmaps or dendrograms using anno_points(), anno_barplot(), and HeatmapAnnotation().
• Splitting heatmaps into sub-panels based on k-means clustering or hierarchical clustering groups.

When NOT to Use

• For simple, single heatmaps without annotations where base R heatmap() is sufficient.
• When you need a purely client-side interactive web heatmap without an R backend (though InteractiveComplexHeatmap can be used within Shiny).

Data Requirements

• A numeric matrix for the main heatmap body.
• Can accept a zero-row or zero-column matrix if you only want to draw dendrograms plus a list of annotations.

Key Parameters

• padding: Used in draw() to manually increase the blank areas around the final plot to prevent text from being cut.
• newpage: Set to FALSE in draw() when using grid.layout() to manage the layout of multiple panels.
• row_split: Splits rows into groups (e.g., passing an integer or a grouping variable from cutree).
• row_km / column_km: Applies k-means clustering to partition rows or columns.
• row_km_repeats / column_km_repeats: Runs k-means multiple times to get a final consensus clustering.
• cluster_rows: Controls row clustering; can accept custom functions like cluster_within_group().
• right_annotation: Adds row annotations to the right side of the heatmap using rowAnnotation().
• heatmap_legend_param: Controls the style of legends within the Heatmap() function.

Best Practices

• Explicitly use the draw() function if no plot appears after running Heatmap().
• For matrices with a huge number of rows or columns, randomly sample them into a reasonably small number to efficiently visualize global patterns.
• Always add set.seed(...) before making a heatmap that uses k-means clustering to ensure the random start points yield reproducible results.
• Use grid.grabExpr(draw(ht)) to capture the heatmap output and later draw it as a single graphic element using grid.draw().

Common Pitfalls

• Text cut off by plotting region: The layout may draw text outside the plotting area. Fix: Set the padding argument in the draw() function to increase blank space.
• Inconsistent k-means clustering: Running the script multiple times yields different clusters due to random initialization. Fix: Set row_km_repeats / column_km_repeats to run k-means multiple times for consensus, or use set.seed().
• Missing axes on dendrograms: Dendrograms do not have axes by default. Fix: Use decorate_row_dend() or decorate_column_dend() along with grid.xaxis() or grid.yaxis() to manually add them.
• Annotation sizing issues: Simple annotations don't scale correctly. Fix: Control simple annotation sizes with anno_simple_size, and set height/width directly inside complex anno_*() functions.

Alternatives

• pheatmap: A simpler package for basic annotated heatmaps (ComplexHeatmap can translate pheatmap calls).
• InteractiveComplexHeatmap: An extension package specifically for making ComplexHeatmap objects interactive in Shiny.
• gplots: Provides heatmap.2() for basic heatmaps with a color key and dendrograms.

Citations

• Gu, Z., Eils, R., & Schlesner, M. (2016). Complex heatmaps reveal patterns and correlations in multidimensional genomic data. Bioinformatics, 32(18), 2847-2849.

References

• Homepage: https://bioconductor.org/packages/ComplexHeatmap
• Vignette: http://jokergoo.github.io/ComplexHeatmap-reference/book/

<!-- biomate-cta -->

---

Run this on BioMate

This skill is the knowledge layer — when, why, and how to use complexheatmap. To run this analysis on your own data with managed compute, automated QC, and reproducible outputs, use BioMate — free to start.

▶ Open complexheatmap on BioMate →