HeatmapR

Overview

HeatmapR is a lightweight R package that uses base graphics to facilitate the creation of high quality complex heatmaps that can be easily arranged with other plots. In this vignette, we will explore the key features of HeatmapR and describe the usage of each of the key functions in HeatmapR as summarised below:

  • heat_map() convenient wrapper around all HeatmapR functions providing an intuitive way to create complex heatmaps using base graphics.
  • heat_map_cor() draws correlation matrices, with one order for the rows and columns and different shapes in each triangle.
  • heat_map_dot() draws dot plots of groups of cells: the colour of each dot shows a group’s mean and its size the proportion of cells in which the feature is detected.
  • heat_map_clust() is used inside heat_map() to perform hierarchical clustering on the dataset, in compiled code that builds the same trees as stats::hclust().
  • heat_map_scale() is used inside heat_map() to apply column- or row-wise mean, z-score, range or quantile scaling, or the asinh transform of cytometry data (Bendall et al. 2011), to the dataset prior to constructing the heatmap.
  • heat_map_summarise() reduces groups of rows or columns to one summary each (e.g. the mean expression of each cell type, or the median of each marker in each cluster), or keeps the values of each group for distributions inside the cells.
  • heat_map_markers() ranks the marker features of groups of cells by their AUC, with Wilcoxon p-values, and heat_map_downsample() keeps at most a number of cells of each group.
  • heat_map_smooth() smooths features along a trajectory (e.g. pseudotime) for heatmaps of genes ordered by when they peak.
  • heat_map_example() simulates the single-cell RNA, cytometry and trajectory data used in the examples and guides.
  • heat_map_threads() sets the number of threads shared by the compiled code.
  • heat_map_info() returns the data, row and column order, clusters, colours and layout of a heatmap for downstream analyses.
  • heat_map_describe() writes a plain-language description of a heatmap to use as alternative text for screen readers.
  • heat_map_data() returns the cells, rows, columns and dendrograms of a heatmap as tidy tables, and heat_map_grob() places heatmaps beside ggplot2 plots.
  • heat_map_layout() allows you to create custom plot layouts to arrange multiple heatmaps.
  • heat_map_save() can be called prior to any heat_map() call to save a high resolution image.
  • heat_map_record() can be called after any heat_map() calls to record the current plot for saving to an R object.
  • heat_map_complete() can be called when creating complex layouts to indicate when the resulting layout should be saved to file using heat_map_save().
  • heat_map_reset() resets all HeatmapR associated settings in case things are not working as they should.

The HeatmapR website has guides that go further, with every figure drawn as the site is built: ordering rows and columns, large heatmaps, single-cell data (SingleCellExperiment, Seurat and cytometry data, markers, dot plots and trajectories), more than colour (uncertainty, split cells, distributions and annotations), working with heatmaps (redraws, tidy data, ggplot2 and alternative text), and a speed comparison with other heatmap packages.

1. Construct a Basic Heatmap

Constructing a heatmap is as simple as loading the HeatmapR package and supplying your dataset to the heat_map() function. The constructed heatmap will be in the same orientation as the input data, the first row at the top and the first column at the left as when the data is printed, and each numeric cell in the heatmap will be coloured using the colour scale supplied to cell_col_scale. By default, heat_map() uses a hybrid colour blind friendly viridis palette to offer high visual contrast.

library(HeatmapR)
heat_map(mtcars)

Heatmap of the unscaled mtcars data with the 32 cars as rows and the 11 variables as columns, coloured on a single scale from 0 to about 470, so that only displacement (disp) and horsepower (hp) stand out and the other variables all look the same.

2. Cell Properties

heat_map() contains a family of cell_ arguments which allow for the customisation of the shape, size, colour, borders and text of cells within a heatmap. In the examples below, we will apply the same properties to every cell within the heatmap, but it is also possible to modify these properties per cell by supplying a matrix matching the dimensionality and orientation of the input matrix.

2.1 Cell Shape

heat_map() supports different cell shapes through the cell_shape argument which can be set to "rect" (default), "circle", "diamond", "ellipse", "number" or "none". Circles and diamonds stay round when the cells aren’t square, sized by the shorter side of the cells. Ellipses show values between -1 and 1, such as correlations, by their shape, "number" writes each value in the colour of its cell, and "none" leaves a cell empty (see Correlation Matrices). Where cells are drawn as shapes that don’t fill them, cell_grid_line_col (e.g. "grey85") draws a light grid around the cells.

heat_map(
  mtcars,
  cell_shape = "circle"
)

The unscaled mtcars heatmap with every cell drawn as a circle of the same size, coloured by its value, with the 32 cars as rows and the 11 variables as columns.

heat_map(
  mtcars,
  cell_shape = "diamond"
)

The unscaled mtcars heatmap with every cell drawn as a diamond of the same size, coloured by its value, with the 32 cars as rows and the 11 variables as columns.

2.2 Cell Size

The size of each cell is controlled through the cell_size argument. Setting cell_size = TRUE will scale the size of each cell based on its value in the input matrix. Alternatively, users can supply a separate matrix of the same dimensionality and orientation as the input matrix to control the size of the cells independently of their colour.

heat_map(
  mtcars,
  cell_shape = "circle",
  legend_size = 1.5,
  cell_size = TRUE
)

The unscaled mtcars heatmap drawn as circles that are both sized and coloured by value, with a colour bar and a size legend, so that the large displacement and horsepower values appear as big circles and the small values shrink to dots.

2.3 Cell Colours

The colour of each cell in the heatmap is dependent on the type of data in that cell. Cells containing numeric values will be assigned colours based on the continuous colour scale supplied to cell_col_scale, whilst cells containing non-numeric values will be assigned colours from the discrete colour palette supplied to cell_col_palette. Missing values of the form NA are also supported and the colour of cells containing missing values can be controlled through the cell_col_empty argument. The cell_col_alpha argument accepts values ranging from zero (transparent) to one (solid) for fine control over the transparency of the colour in each cell of the heatmap. In the example below, we will demonstrate the handling of different data types within heat_map() using a modified subset of the iris dataset where additional missing values have been introduced:

# Modified subset of iris dataset with missing values
iris_sub <- iris[sample(1:nrow(iris), 25), ]
iris_sub[c(2, 19, 14, 7), 2] <- NA
iris_sub[c(4, 9, 17, 25), 3] <- NA

# Build heatmap
heat_map(
  iris_sub,
  cell_text = TRUE,
  cell_col_empty = "grey40",
  cell_col_scale = c(
    "yellow",
    "orange",
    "red",
    "black"
  ),
  cell_col_palette = c(
    "magenta",
    "blue",
    "green3"
  ),
  cell_col_alpha = 1
)

Heatmap of 25 randomly sampled rows of the iris data with each value written in its cell, the four measurements coloured on a yellow to black scale, the Species column coloured by species with a legend of the species, and the missing values shown as empty grey cells.

2.3.1 Uncertainty in Colour

Estimates such as fold changes come with uncertainty, and a noisy estimate shouldn’t look as strong as a precise one. cell_uncertainty takes a matrix of uncertainties (standard errors, confidence interval widths or p-values) and colours the cells with a value-suppressing palette (Correll, Moritz and Heer 2018): the more uncertain a value, the fewer colours its part of the scale has and the closer they are to grey. Precise values use eight colours across the scale, then four, two, and the most uncertain values a single, nearly grey colour. cell_uncertainty_breaks sets the thresholds between the levels, and the colour legend becomes a key with one row per level.

set.seed(3)
genes <- c("IFIT1", "ISG15", "MX1", "OAS1", "IRF7", "STAT1", "CXCL10",
           "GBP1", "IL6", "TNF", "CCL2", "NFKBIA", "SOCS3", "JUNB")
times <- c("6 h", "12 h", "24 h", "48 h", "72 h", "96 h")
# log2 fold changes and their standard errors
lfc <- outer(
  c(rep(2.4, 7), rep(-1.6, 4), rep(0.6, 3)),
  c(0.5, 1, 1.2, 1, 0.7, 0.4)
) + matrix(rnorm(84, 0, 0.5), 14)
se <- matrix(rgamma(84, 2, 6), 14) *
  rep(c(1, 1, 1, 3, 1, 1, 4, 1, 2.5, 3.5, 1, 1, 5, 1), 6)
dimnames(lfc) <- dimnames(se) <- list(genes, times)
heat_map(
  lfc,
  tree_y = TRUE,
  cell_col_scale = "Blue-Red 3",
  cell_col_scale_limits = c(-3, 3),
  cell_uncertainty = se,
  cell_uncertainty_breaks = c(0.3, 0.6, 0.9),
  cell_uncertainty_title = "SE",
  legend_title = "log2 FC",
  title = "Fold changes, faded where they're uncertain"
)

Heatmap of simulated log2 fold changes for 14 genes over six time points, with the genes clustered by a dendrogram, in which precise estimates use the full blue to red scale and uncertain ones fade towards grey, and a legend with one row of colours for each level of standard error.

2.3.2 Two Values in Each Cell

To compare two conditions cell by cell, such as control and stimulated samples or two time points, cell_split takes a second matrix with the same dimensions as the data. Each cell is split along its diagonal: the value in x fills the upper left half and the value in cell_split the lower right half, on the same colour scale, whose limits cover both. Changes then show up as cells with two colours, without doubling the size of the heatmap. cell_split_labels names the two halves in the legend.

set.seed(6)
types <- c("B", "CD4 T", "CD8 T", "NK", "Mono", "DC")
genes <- c("IFNG", "GZMB", "PRF1", "TNF", "IL2RA", "CD69", "HLA-DR",
           "CD86", "IL10", "CXCL8")
# Expression in each cell type before and after stimulation
control <- matrix(rnorm(60, 0, 0.6), 10, dimnames = list(genes, types))
stimulated <- control + matrix(rnorm(60, 0, 0.3), 10)
stimulated["IFNG", c("CD4 T", "CD8 T", "NK")] <-
  stimulated["IFNG", c("CD4 T", "CD8 T", "NK")] + c(1.8, 2.6, 2.9)
stimulated["GZMB", c("CD8 T", "NK")] <- stimulated["GZMB", c("CD8 T", "NK")] + 2.2
stimulated["CD69", ] <- stimulated["CD69", ] + 1.4
stimulated["IL10", "Mono"] <- stimulated["IL10", "Mono"] + 2.4
stimulated["CD86", c("Mono", "DC")] <- stimulated["CD86", c("Mono", "DC")] + 1.6
heat_map(
  control,
  cell_split = stimulated,
  cell_split_labels = c("Control", "Stimulated"),
  tree_y = TRUE,
  legend_title = "Expression",
  title = "Control and stimulated in each cell"
)

Heatmap of simulated expression of 10 genes in six immune cell types, with each cell split along its diagonal into a control half (upper left) and a stimulated half (lower right) on one colour scale, the genes clustered by a dendrogram and a legend naming the two halves.

Split cells need full-size rectangles or circles: circles (cell_shape = "circle") are split down the middle instead, x on the left and cell_split on the right, and each half can have its own size (cell_size and cell_split_size), as in the split dots of heat_map_dot(split_by = ).

2.4 Cell Borders

The borders of every cell within the constructed heatmap can also be customised using the cell_border_line_type, cell_border_line_width, cell_border_line_col and cell_border_line_col_alpha arguments.

heat_map(
  mtcars,
  cell_border_line_type = 3,
  cell_border_line_width = 2,
  cell_border_line_col = "red",
  cell_border_line_col_alpha = 1
)

The unscaled mtcars heatmap with every cell outlined by a thick dotted red border.

2.4.1 Border Masking

The cell_border_mask argument allows you to selectively apply coloured borders to specific cells by supplying a logical matrix of the same dimensions as the input data. Cells with TRUE values will display colored borders, while cells with FALSE values will have transparent borders. This is particularly useful for highlighting specific patterns or regions of interest within a heatmap.

# Create a mask to highlight high values
border_mask <- mtcars > median(unlist(mtcars))

heat_map(
  mtcars,
  cell_border_line_width = 2,
  cell_border_line_col = "red",
  cell_border_mask = border_mask,
  cell_text = TRUE,
  title = "Border Masking Example"
)

The unscaled mtcars heatmap, titled Border Masking Example, with each value written in its cell and red borders drawn only around the cells whose values are above the median of the whole data set.

2.5 Cell Text

The values of every cell within the constructed heatmap can be displayed by setting cell_text = TRUE. By default, numeric values are rounded to two decimal places but this can be changed through the round argument. The text displayed in each cell can easily be customised using the cell_text_size, cell_text_font, cell_text_col and cell_text_col_alpha arguments.

heat_map(
  mtcars,
  cell_text = TRUE,
  cell_text_size = 1,
  cell_text_font = 2,
  cell_text_col = "black",
  cell_text_col_alpha = 1,
  cell_col_alpha = 0.9,
  title = "mtcars"
)

The unscaled mtcars heatmap, titled mtcars, with each value written in bold black text in its cell.

2.6 Large Heatmaps

Heatmaps with more than 50,000 cells, such as single-cell data with thousands of cells and tens of markers, are drawn as raster images rather than one rectangle per cell. Raster images draw large heatmaps many times faster (a 1000 x 1000 heatmap in about 0.15 seconds) and give PDFs a fraction of the size, and look the same as the rectangles. Raster images are only used when every cell is a full-size rectangle; cell_raster = TRUE uses them for smaller heatmaps too and cell_raster = FALSE turns them off. Cell borders are left out when the cells are smaller than three line widths, as they would otherwise hide the cells.

set.seed(1)
cells <- matrix(
  rnorm(5000 * 20),
  nrow = 5000,
  dimnames = list(
    NULL,
    paste0("Marker_", 1:20)
  )
)
cells[1:1500, 1:8] <- cells[1:1500, 1:8] + 2.5
cells[3001:5000, 12:20] <- cells[3001:5000, 12:20] + 2
heat_map(
  cells,
  tree_x = TRUE,
  tree_cut_y = 3,
  tree_label_y = TRUE,
  tree_label_text_y = c("A", "B", "C"),
  axis_text_y = NA,
  title = "5000 cells"
)

Heatmap of 5,000 simulated cells by 20 markers drawn as a raster image, with the markers clustered by a dendrogram and the cells cut into three clusters labelled A, B and C: A is high in markers 12 to 20, B in markers 1 to 8 and C in neither.

Clustering is the slow part of a large heatmap. It needs the distance between every pair of rows, so exact clustering of 10,000 rows takes about 1.5 seconds on two cores and 400 MB of memory, and four times as much for twice the rows. Rows (or columns) beyond clust_max, 5000 by default, are clustered in two stages instead. A sample of 5000 rows is clustered exactly and its dendrogram is split into groups of about 200 rows, every row joins the group whose medoid it is closest to, and each group is clustered on its own beneath the sample’s dendrogram. The sample is drawn with a fixed seed, so the dendrogram is the same each time. The dendrogram shows the structure of the data down to the groups and within each group, and 100,000 rows take about half a second. clust_max = Inf always clusters exactly, and heat_map_clust() takes the same limit as max. Branch support is only computed for up to clust_max rows or columns, and optimal leaf ordering (tree_order_y = "olo") is exact for up to 4000 rows (0.3 seconds) and orders blocks of larger dendrograms. Distances, linkage, cuts, k-means and leaf ordering run in compiled C++ code.

set.seed(1)
cells <- matrix(
  rnorm(100000 * 20),
  nrow = 100000,
  dimnames = list(
    NULL,
    paste0("Marker_", 1:20)
  )
)
cells[1:30000, 1:8] <- cells[1:30000, 1:8] + 2.5
cells[60001:100000, 12:20] <- cells[60001:100000, 12:20] + 2
heat_map(
  cells,
  tree = "both",
  tree_cut_y = 3,
  axis_text_y = NA,
  title = "100,000 cells"
)

2.7 Labelling Chosen Rows and Columns

When a heatmap has too many rows to label them all, mark_y (and mark_x for columns) labels just the rows you choose, given as names, positions in the heatmap (rows from the top) or a logical vector in the order of the data. The labels replace the axis text: they are spread out beside the heatmap so that they don’t overlap, and leader lines connect each label to its row. mark_labels_y supplies other text for the labels (e.g. gene symbols), and mark_line_col sets the colour of the leader lines.

set.seed(2)
genes <- matrix(
  rnorm(2000 * 24),
  nrow = 2000,
  dimnames = list(
    paste0("Gene_", 1:2000),
    paste0("S", 1:24)
  )
)
genes[1:150, 1:12] <- genes[1:150, 1:12] + 2.5
genes[1001:1150, 13:24] <- genes[1001:1150, 13:24] + 2.5
heat_map(
  genes,
  tree_x = TRUE,
  tree_cut_y = 2,
  mark_y = c("Gene_3", "Gene_42", "Gene_77", "Gene_150", "Gene_1010", "Gene_1100", "Gene_1500"),
  mark_labels_y = c("CD3E", "CD4", "IL7R", "CCR7", "MS4A1", "CD79A", "ACTB"),
  title = "Marker genes"
)

Heatmap of 2,000 simulated genes across 24 samples, clustered in both directions with the genes cut into two clusters, in which seven chosen genes (MS4A1, CD79A, IL7R, CD4, CCR7, CD3E and ACTB) are labelled beside the heatmap with leader lines to their rows instead of all the gene names.

2.7.1 Zooming Into a Band of Rows

Mark labels name a few rows, but they don’t show their values. zoom_y (and zoom_x for columns) enlarges a band of rows in a panel beside the heatmap instead, so the detail of a few rows can be read together with the whole. The band runs from the first to the last of the rows you choose in the displayed order (giving the first and last rows is enough), is outlined on the heatmap and joined to the panel by a wedge. The panel sits on the axis text side and is labelled with the names of the enlarged rows, in place of the axis text. zoom_size_y sets the width of the panel relative to the heatmap (by default the same width for a panel as long as the heatmap, and narrower for a shorter panel, so that enlarging a few rows doesn’t halve the heatmap), and enlarged rows are at most 0.3 inches tall.

set.seed(2)
genes <- matrix(
  rnorm(2000 * 24),
  nrow = 2000,
  dimnames = list(
    paste0("Gene_", 1:2000),
    paste0("S", 1:24)
  )
)
genes[1:150, 1:12] <- genes[1:150, 1:12] + 2.5
genes[1001:1150, 13:24] <- genes[1001:1150, 13:24] + 2.5
# 20 genes of a pathway - up in half of each group of samples
genes[151:170, c(1:6, 13:18)] <- genes[151:170, c(1:6, 13:18)] + 3
rownames(genes)[151:170] <- c(
  "IL7R", "CCR7", "SELL", "LEF1", "TCF7", "CD27", "CD28", "KLF2", "S1PR1",
  "FOXP1", "BACH2", "SATB1", "PLAC8", "LTB", "MAL", "NOSIP", "PIK3IP1",
  "TXK", "AQP3", "CD7"
)
heat_map(
  genes,
  scale = "row",
  tree_x = TRUE,
  zoom_y = c("IL7R", "CD7"),
  title = "A pathway in 2,000 genes"
)

Row-scaled heatmap of 2,000 simulated genes across 24 clustered samples, in which a thin band of 20 pathway genes is outlined and joined by a wedge to an enlarged panel on the left that names each gene and shows its values cell by cell.

The panel keeps the cells’ shapes, text and distributions and the gaps between clusters. Rows that are far apart in a clustered heatmap make a wide band; to enlarge one cluster, pass its rows, e.g. zoom_y = heat_map_info(hm)$row_clusters == 2.

2.8 Rotated Column Labels

Long column names are easier to read at an angle. As well as the las codes 0 to 3 (3, perpendicular to the axis, by default), axis_text_angle_x takes an angle in degrees. Rotated labels end at their ticks and slant towards the y axis text, so the longest labels extend beneath the row names rather than into the dendrograms or the legend. They are only shrunk when neighbouring labels would overlap across their baselines, so they stay larger than perpendicular labels on crowded heatmaps.

heat_map(
  t(scale(mtcars)),
  tree = "both",
  axis_text_angle_x = 45
)

Heatmap of the z-scored mtcars data transposed so that the 11 variables are rows and the 32 cars are columns, clustered in both directions with dendrograms, with the car names written at a 45 degree angle beneath it.

2.9 Correlation Matrices

heat_map_cor() draws the correlations between the columns of a data set (or a correlation matrix) with one order for the rows and columns, so that the diagonal runs from the top left to the bottom right and each triangle can show the correlations differently. By default, the variables are clustered on one minus their correlations, the lower triangle shows ellipses, the upper triangle the correlation coefficients written in their colours, and the diagonal the names of the variables. Each ellipse is the outline of a bivariate normal distribution with that correlation (Murdoch and Chow 1996): a circle for uncorrelated variables, rising to the right for positive correlations, falling for negative ones, and narrower the stronger the correlation.

heat_map_cor(mtcars)

Correlation heatmap of the mtcars variables, clustered so that correlated variables sit together, with ellipses in the lower triangle, the coefficients written in blue (negative) or red (positive) in the upper triangle and the variable names on the diagonal.

lower, upper and diag take any cell shape - "circle" and "diamond" are sized by the absolute correlation, and "none" leaves a triangle empty - and any other heat_map() argument can be added, such as cuts that split the variables into clusters along both axes:

heat_map_cor(
  mtcars,
  method = "spearman",
  upper = "ellipse",
  tree_cut_x = 3,
  tree_cut_y = 3
)

Spearman correlations of the mtcars variables drawn as ellipses throughout, with the variables split into three clusters along both axes.

For other layouts, the shapes can be set cell by cell in heat_map() with a matrix of shapes, e.g. ellipses for the correlations of each gene with a set of clinical variables and numbers for the strongest ones.

3. Data Scaling

In the above heatmap, it is very clear that each of the columns of the input matrix are on completely different scales, making it difficult to visualise differences in columns with very small values. In order to represent each column on the same scale, we can apply a form of data scaling through the scale_method argument either to each row or column as specified by the scale argument. heat_map() has internal support for "mean", "range", "zscore" and "quantile" scaling methods (see heat_map_scale()), which can be applied to either the rows or columns of the input matrix, and transform = "asinh" transforms cytometry values before scaling.

3.1 Scaling Columns

To scale the values in every column, simply set scale = "column" and specify the scaling method through the scale_method argument. For example, to apply range scaling to every column in the mtcars dataset:

heat_map(
  mtcars,
  scale = "column",
  scale_method = "range",
  title = "mtcars scaled columns"
)

The mtcars heatmap with each column rescaled from 0 to 1, titled mtcars scaled columns, so that differences between the cars are now visible in every variable.

3.2 Scaling Rows

Similarly, in instances where it is more appropriate to scale the values in each row, we can set scale = "row" and pass the required scaling method to scale_method. For example, to apply z-score scaling to every row in the mtcars dataset:

heat_map(
  mtcars,
  scale = "row",
  scale_method = "zscore",
  title = "mtcars scaled rows"
)

The mtcars heatmap with each row converted to z-scores, titled mtcars scaled rows, in which displacement and horsepower are the highest values for every car and the other variables are all low.

4. Bar Plots

In addition to the cells of the heatmap, heat_map() supports the display of additional values in bar plots on either axis of the heatmap. To add bar plots to the heatmap, users should supply the (named) values to bar_values_x and/or bar_values_y in the same order as the original input matrix. The bar plots will be displayed on the opposite side to the axis text and size of the bar plot (i.e. height or width) can be controlled through the bar_size_x and bar_size_y arguments. The colours of the bars and borders can be customised using the bar_fill_ and bar_line_ family of arguments. In the example below, we demonstrate the addition of bar plots to the x and y axes of a heatmap constructed using the mtcars dataset:

heat_map(
  mtcars,
  bar_values_x = 1:ncol(mtcars),
  bar_size_x = 1.5,
  bar_fill_x = rainbow(ncol(mtcars)),
  bar_line_col_x = "black",
  bar_values_y = 1:nrow(mtcars),
  bar_size_y = 0.8,
  bar_fill_y = rainbow(nrow(mtcars)),
  bar_line_col_y = "black",
  title = "heatmap with bar plots"
)

The unscaled mtcars heatmap, titled heatmap with bar plots, with a bar plot above it showing the values 1 to 11 for the columns and a bar plot to its right showing the values 1 to 32 for the rows, the bars filled with rainbow colours.

4.1 Metadata Annotations

Metadata describing the rows or columns of the heatmap, such as the treatment and sex of each sample, can be shown as coloured tracks beside the heatmap. Supply a data.frame with one row per column of x to annotation_x (or one row per row of x to annotation_y). Rows are matched to the column (row) names of x when the data.frame has row names. Each column of the data.frame becomes a track: non-numeric columns are coloured by level and numeric columns with a colour ramp, and each track gets its own legend. Colours can be chosen through annotation_colours, a named list with one entry per annotation; annotations without an entry get default palettes.

Annotations combine well with manual clustering: supplying a factor to tree_cut_x splits the columns into groups and, when tree_label_x = TRUE, labels each group with its level.

set.seed(123)
mat <- matrix(
  rnorm(20 * 24, sd = 1.5),
  nrow = 20,
  ncol = 24,
  dimnames = list(
    paste0("Gene_", 1:20),
    paste0("S", sprintf("%02d", 1:24))
  )
)
meta <- data.frame(
  Treatment = factor(rep(c("Control", "Drug_A", "Drug_B"), each = 8)),
  Sex = factor(rep(c("Male", "Female"), times = 12), levels = c("Male", "Female")),
  row.names = colnames(mat)
)
heat_map(
  mat,
  annotation_x = meta,
  annotation_colours = list(
    Treatment = c(Control = "#4E9FD1", Drug_A = "#E07B54", Drug_B = "#6DBF7E"),
    Sex = c(Male = "#7B5EA7", Female = "#E8A0BF")
  ),
  tree_cut_x = meta$Treatment,
  tree_label_x = TRUE,
  tree_y = TRUE,
  cell_col_scale = c("#2C7BB6", "white", "#D7191C"),
  cell_col_scale_center = 0,
  legend_title = "z-score",
  title = "Metadata annotations"
)

Heatmap of 20 simulated genes across 24 samples on a blue-white-red z-score scale, with the samples split into labelled Control, Drug_A and Drug_B groups, coloured Treatment and Sex annotation tracks above the columns with their own legends, and the genes clustered by a dendrogram.

4.2 Box Plots and Violins

The bar plots can also show the distribution of several values for each column or row, as box plots (bar_type_x = "box") or violins (bar_type_x = "violin", Hintze and Nelson 1998). Supply a list with a numeric vector for each column (or row), a matrix or data.frame with one column per column of the heatmap (one row per row for bar_values_y), or TRUE to show the values of each column or row of the heatmap itself. Box plots are drawn by default when distributions are supplied. In the example below, the heatmap shows the median intensity of each marker in each cluster of simulated cytometry events (computed with heat_map_summarise(), see section 5.3), the violins show the distribution of each marker across all events, and the bars show the size of each cluster:

set.seed(7)
markers <- c("CD3", "CD4", "CD8", "CD19", "CD56", "CD14")
pops <- list(
  "CD4 T" = c("CD3", "CD4"),
  "CD8 T" = c("CD3", "CD8"),
  "B" = "CD19",
  "NK" = "CD56",
  "Monocyte" = c("CD4", "CD14")
)
cluster <- sample(
  names(pops),
  5000,
  replace = TRUE,
  prob = c(0.35, 0.2, 0.15, 0.1, 0.2)
)
events <- matrix(
  rnorm(5000 * 6, 0.5, 0.5),
  ncol = 6,
  dimnames = list(NULL, markers)
)
for (p in names(pops)) {
  ind <- cluster == p
  events[ind, pops[[p]]] <- rnorm(sum(ind) * length(pops[[p]]), 4, 0.6)
}
heat_map(
  heat_map_summarise(events, group_y = cluster, fun = "median"),
  cell_col_scale = "viridis",
  bar_values_x = events,
  bar_type_x = "violin",
  bar_size_x = 2,
  bar_fill_x = "grey85",
  bar_axis_label_x = "All events",
  bar_values_y = table(cluster),
  bar_fill_y = "grey85",
  bar_axis_label_y = "Events",
  title = "Median marker intensity per cluster"
)

Heatmap of the median intensity of six markers in five clusters of simulated cytometry events, each cluster bright only in its defining markers, with violins above showing the distribution of each marker across all events and bars on the right showing the number of events in each cluster.

5. Hierarchical Clustering

heat_map() also supports hierarchical clustering to construct dendrograms, and cuts the dendrograms into distinct clusters (giving the clusters of stats::cutree()). Distances and linkage are computed in compiled code using the nearest-neighbour chain algorithm (Murtagh 1983; Müllner 2011), which builds the same trees as stats::hclust() (when distances are tied, as they often are for integer data, the tree can make a different but equally valid choice between the tied merges). The dist_method and clust_method arguments allow for control over the distance metric to use for hierarchical clustering (any method supported by stats::dist(), "cosine" for cosine distance, "pearson", "spearman" or "kendall" for correlation distances, or a function) and the agglomeration method to use (any method supported by stats::hclust()).

5.1 Dendrograms

Dendrograms can be added to the x and/or y axis using the tree, tree_x or tree_y arguments. The tree argument indicates whether dendrograms should be drawn for the "x", "y" or "both" axes. Alternatively, the tree_x or tree_y arguments can be set to TRUE to include dendrograms on the x or y axes respectively. The tree_x and tree_y arguments also accept objects of class dist or hclust to allow for custom dendrograms using unsupported distance metrics or agglomeration methods. The tree_size_x and tree_size_y arguments are scalars to control the height or width of the dendrograms on the x and y axes respectively. The tree_scale_x and tree_scale_y arguments can be used to scale the branch heights of the dendrogram to be the same height at each level allowing for better visualisation of relationships in large heatmaps.

heat_map(
  mtcars,
  scale = "column",
  dist_method = "euclidean",
  clust_method = "complete",
  tree_x = TRUE,
  tree_y = TRUE,
  tree_size_y = 0.8,
  tree_scale_x = TRUE,
  title = "Dendrograms"
)

The column-scaled mtcars heatmap, titled Dendrograms, with the cars and the variables reordered by hierarchical clustering and dendrograms drawn to the right of the rows and above the columns.

5.1.1 Cosine Distance

In addition to the standard distance metrics supported by stats::dist(), HeatmapR also supports cosine distance for hierarchical clustering. Cosine distance (1 - cosine similarity) measures the angle between vectors and is particularly useful for high-dimensional data where the magnitude of the vectors is less important than their direction. This is especially valuable when analysing gene expression data or other normalised datasets.

heat_map(
  mtcars,
  scale = "column",
  dist_method = "cosine",
  clust_method = "complete",
  tree_x = TRUE,
  tree_y = TRUE,
  tree_size_y = 0.8,
  tree_scale_x = TRUE,
  title = "Cosine Distance Clustering"
)

The column-scaled mtcars heatmap, titled Cosine Distance Clustering, with the cars and the variables clustered on cosine distance and dendrograms drawn to the right of the rows and above the columns.

Absolute Distance Thresholds: When using cosine distance, tree_cut values between 0 and 1 are interpreted as absolute cosine distance thresholds rather than proportional tree heights. For example, tree_cut_x = 0.5 means cluster at cosine distance of 0.5, not at 50% of the tree height. This provides more intuitive control over clustering based on actual distance values.

# Cut at absolute cosine distance of 0.5
heat_map(
  mtcars,
  scale = "column",
  dist_method = "cosine",
  tree_x = TRUE,
  tree_cut_x = 0.5,
  tree_split_x = 1,
  title = "Cosine Distance with Absolute Threshold"
)

Correlation distances and leaf order: dist_method also accepts "pearson", "spearman" and "kendall" for one minus the correlation, which groups rows that rise and fall together whatever their level (common for gene expression), or a function that takes the matrix being clustered and returns a dist object. A dendrogram can be drawn in many orders, as every branch can be flipped; tree_order_x and tree_order_y choose the order. "olo" (optimal leaf ordering, Bar-Joseph, Gifford and Jaakkola 2001) flips branches so that neighbouring rows are as similar as possible, giving smoother gradients, and "mean" orders branches by their mean values (stats::heatmap() uses the sum of their leaves’ means, which favours small branches).

set.seed(5)
mat <- matrix(
  rnorm(60 * 12),
  nrow = 60,
  dimnames = list(
    paste0("Gene_", 1:60),
    paste0("S", 1:12)
  )
)
# 20 genes that rise and fall together at different levels
profile <- rnorm(12)
mat[1:20, ] <- t(replicate(20, 3 * profile + rnorm(12, sd = 0.5))) +
  rnorm(20, sd = 4)
heat_map(
  mat,
  tree = "both",
  dist_method = "pearson",
  tree_order_x = "olo",
  tree_order_y = "olo",
  axis_text_y = NA,
  title = "Pearson distance, optimal leaf order"
)

Heatmap of 60 simulated genes across 12 samples clustered in both directions on Pearson correlation distance with optimal leaf ordering, in which the 20 genes that rise and fall together, at different levels, form a block at the bottom whose values increase smoothly from left to right across the reordered samples.

5.1.2 Spectral Ordering

A dendrogram orders rows by flipping whole branches, so data that change gradually rather than fall into groups, such as cells along a differentiation trajectory or samples along a time course, come out in pieces. tree_order_y = "spectral" (and tree_order_x) orders the rows along the main path through the data instead, and needs no dendrogram. Each row is joined to its 6 nearest neighbours (by dist_method) in a graph, the graph is split recursively where it is thinnest (Shi and Malik 2000), each part is sorted by its Fiedler vector (the second eigenvector of the graph; Fiedler 1973, Atkins, Boman and Hendrickson 1998) with the halves turned to meet where they are closest, and runs of up to 12 rows are then reversed wherever that brings similar rows together (a windowed 2-opt, Croes 1958). Gradients and trajectories are laid out along their length, cycles around their loop and clusters one after another. In the example below, 400 cells are sampled at random times along a trajectory in which 12 genes peak in turn, and the cells and genes are shuffled: the spectral order recovers the times of the cells (a rank correlation of 0.998 with their order) and the order of the genes, and the cascade of peaks runs down the diagonal.

set.seed(3)
# 400 cells at random times along a trajectory, 12 genes peaking in turn
time <- runif(400)
peak <- seq(0, 1, length.out = 12)
cells <- outer(time, peak, function(t, p) 4 * exp(-(t - p)^2 / 0.02)) +
  matrix(rnorm(400 * 12, sd = 0.4), 400)
dimnames(cells) <- list(paste0("Cell_", 1:400), paste0("Gene_", 1:12))
# shuffle the genes (the cells are already in random order)
cells <- cells[, sample(12)]
heat_map(
  cells,
  tree_order_x = "spectral",
  tree_order_y = "spectral",
  axis_text_y = NA,
  title = "Spectral order of cells and genes"
)

Heatmap of 400 simulated cells as rows and 12 genes as columns, both in spectral order without dendrograms, in which the genes run from Gene_1 to Gene_12 and the high values of each gene follow one another in a band from the top left to the bottom right, as the cells progress along their trajectory.

With a dendrogram (tree_y = TRUE), "spectral" orders its branches by the mean spectral position of their rows instead, so the dendrogram is kept and a gradient runs in one direction across it. Rows grouped by tree_cut_y or tree_kmeans_y without a dendrogram keep the spectral order within each group. Up to clust_max rows are ordered exactly, 5000 in under half a second; larger data is ordered from a sample of clust_max landmark rows, with every other row placed beside its nearest landmark (200,000 rows take about 4 seconds).

5.1.3 Branch Support

A dendrogram always has branches, whether or not the data support them. tree_support_y (and tree_support_x) shows how stable each branch is: the columns are resampled with replacement, the rows are clustered again in the same way, and each branch scores the proportion of resamples in which its exact set of rows is a branch again (its bootstrap support, Felsenstein 1985). Branches with 90% support or more are drawn as thick black lines, 70-89% as grey lines and anything less as dashed lines, and the larger branches are labelled with their support. In mtcars only small groups, such as the Mazda RX4 pair, are stable; most of the larger splits come back less than half the time, which is worth knowing before cutting clusters from the dendrogram. TRUE uses 100 resamples, and the support is the same each time the heatmap is drawn.

heat_map(
  mtcars,
  scale = "column",
  tree = "both",
  tree_size_y = 2,
  tree_support_x = 200,
  tree_support_y = 200,
  title = "Bootstrap support of each branch"
)

The column-scaled mtcars heatmap clustered in both directions, with each dendrogram branch drawn as a thick black, thin grey or dashed line according to its bootstrap support and the larger branches labelled with percentages, showing that only small groups such as the Mazda RX4 pair are strongly supported.

5.2 Clustering

The dendrograms on either axis can be optionally cut to reveal clusters in the data. Dendrogram cutting is performed via the tree_cut_x and tree_cut_y arguments which accept either a fixed number of clusters or a proportion of the total dendrogram height where the cut should be made. The clusters can be spatially separated by introducing splits in the heatmap using the tree_split_x and tree_split_y arguments which are scalars that control the height or width of the splits.

heat_map(
  mtcars,
  scale = "column",
  dist_method = "euclidean",
  clust_method = "complete",
  tree_x = TRUE,
  tree_cut_x = 4,
  tree_split_x = 1,
  tree_y = TRUE,
  tree_size_y = 0.8,
  tree_cut_y = 5,
  tree_split_y = 1,
  title = "Hierarchical Clustering"
)

The column-scaled mtcars heatmap, titled Hierarchical Clustering, with dendrograms on both axes cut into 5 groups of cars and 4 groups of variables, separated by gaps.

In addition to heatmap splitting, heat_map() also supports the labelling of clusters through the tree_label_x, tree_label_text_x, tree_label_y and tree_label_text_y arguments.

heat_map(
  mtcars,
  scale = "column",
  tree_cut_x = 4,
  tree_split_x = 1,
  tree_label_x = TRUE,
  tree_label_text_x = c(1:4),
  tree_label_col_x = c(
    "red",
    "blue", 
    "green", 
    "magenta"
  ),
  tree_y = TRUE,
  tree_size_y = 0.8,
  tree_cut_y = 5,
  tree_split_y = 1,
  tree_label_y = TRUE,
  tree_label_text_y = c(1:5),
  tree_label_col_y = c(
    "red",
    "blue", 
    "green", 
    "magenta",
    "orange"
  ),
  title = "Cluster Labels"
)

The column-scaled mtcars heatmap, titled Cluster Labels, split into 4 groups of variables and 5 groups of cars, each group marked by a coloured bar numbered 1 to 4 above the columns or 1 to 5 beside the rows.

The branches of each cluster can be coloured too: tree_col_x and tree_col_y take one colour for each cluster (from left to right and from top to bottom), or TRUE for distinct colours, and colour the branches within each cluster and the edge into it, while the branches joining clusters stay black. With TRUE the clusters take the colours of hcl.colors(k, "Dark 3"), and the cluster labels take the colours of their branches unless tree_label_col_y is given:

heat_map(
  mtcars,
  scale = "column",
  tree_y = TRUE,
  tree_size_y = 0.8,
  tree_cut_y = 5,
  tree_split_y = 1,
  tree_col_y = TRUE,
  tree_label_y = TRUE,
  title = "Branch Colours"
)

The column-scaled mtcars heatmap, titled Branch Colours, with a row dendrogram cut into 5 groups of cars: the branches of each group drawn in its own colour, matching the coloured label bar beside its rows, and the branches joining the groups in black.

5.2.1 Choosing the Number of Clusters

tree_cut_y = "auto" (or tree_cut_x) chooses the number of clusters from the data. The dendrogram is cut into 2 to 20 clusters, and the cut with the largest mean silhouette width (Rousseeuw 1987) is kept: each row’s silhouette compares its mean distance to the other rows of its cluster with its mean distance to the rows of the nearest other cluster, from 1 (well inside its cluster) through 0 (between two clusters) to -1 (closer to another cluster). Kaufman and Rousseeuw (1990) read a mean width above 0.7 as strong structure, above 0.5 as reasonable structure and above 0.25 as weak structure; when no cut reaches 0.25 the dendrogram isn’t cut. The widths of every cut are computed together, so trying 19 cuts takes little longer than one, and dendrograms with more than clust_max rows are scored on a sample of clust_max of them. The widths are returned with the dendrogram, and heat_map_describe() reports the choice.

set.seed(6)
# 4 groups of 30 samples, 10 measurements
centres <- matrix(rnorm(4 * 10, sd = 3), 4)
groups <- centres[rep(1:4, each = 30), ] + matrix(rnorm(120 * 10), 120)
hm <- heat_map(
  groups,
  tree_y = TRUE,
  tree_cut_y = "auto",
  tree_label_y = TRUE,
  axis_text_y = NA,
  popup = FALSE
)
round(heat_map_info(hm)$tree_y$auto_cut$silhouette[1:6], 2)
#>    2    3    4    5    6    7
#> 0.40 0.59 0.69 0.56 0.41 0.28

The four groups are found (a mean width of 0.69), and heat_map_describe(hm) says so: “The dendrogram was cut automatically into 4 clusters, the number from 2 to 20 with the largest mean silhouette width (0.69, reasonable structure on Kaufman and Rousseeuw’s scale).”

heat_map_clust(cut = "auto") makes the same choice for a dendrogram on its own, and returns the widths in its auto_cut element.

5.2.2 Manual Clustering

In addition to automatic hierarchical clustering, HeatmapR allows you to manually define clusters in two ways: by specifying the number of elements in each cluster, or by providing a vector of cluster indices. This is particularly useful when you want to group data based on domain knowledge or external factors rather than hierarchical relationships.

Method 1: Specify cluster sizes - Provide a vector indicating the number of rows/columns in each cluster:

# Manual clustering by specifying cluster sizes
# Create 3 clusters: 4 columns, 3 columns, 4 columns
heat_map(
  mtcars,
  scale = "column",
  tree_cut_x = c(4, 3, 4),
  tree_split_x = 1,
  tree_label_x = TRUE,
  tree_label_text_x = c("Group A", "Group B", "Group C"),
  tree_label_col_x = "white",
  title = "Manual Clustering by Size"
)

The column-scaled mtcars heatmap, titled Manual Clustering by Size, with the variables kept in their original order and split into groups of 4, 3 and 4 columns labelled Group A, Group B and Group C.

Method 2: Specify cluster indices - Provide a vector where each element indicates which cluster that row/column belongs to. Numeric indices are given as the heatmap is displayed - columns from the left, rows from the top, in the dendrogram order when a dendrogram is drawn and in the order of the data otherwise - so you can draw a heatmap, read it, and assign clusters to what you see. Labels given as characters or a factor (e.g. treatments from sample metadata) follow the original order of the data, and named vectors are matched by name. The rows/columns are regrouped so that each cluster is contiguous in the heatmap:

# Manual clustering by assigning cluster indices
# Assign each of the 11 columns to specific clusters
cluster_indices <- c(1, 1, 1, 1, 2, 2, 2, 3, 3, 3, 3)

heat_map(
  mtcars,
  scale = "column",
  tree_cut_x = cluster_indices,
  tree_split_x = 1,
  tree_label_x = TRUE,
  tree_label_text_x = c("Low", "Medium", "High"),
  tree_label_col_x = c("blue", "yellow", "red"),
  title = "Manual Clustering by Index"
)

The column-scaled mtcars heatmap, titled Manual Clustering by Index, with the variables split into three groups of 4, 3 and 4 columns labelled Low, Medium and High on blue, yellow and red bars.

Manual clusters can be combined with dendrograms by setting tree_x = TRUE or tree_y = TRUE. The rows or columns are then clustered within each cluster, and the clusters are joined at the top of the dendrogram, so each group (e.g. a treatment, or a cell type) gets its own dendrogram:

set.seed(4)
mat <- matrix(
  rnorm(40 * 24),
  nrow = 40,
  dimnames = list(
    paste0("Gene_", 1:40),
    paste0("S", sprintf("%02d", 1:24))
  )
)
treatment <- factor(
  rep(c("Control", "Drug_A", "Drug_B"), times = 8),
  levels = c("Control", "Drug_A", "Drug_B")
)
mat[1:10, treatment == "Drug_A"] <- mat[1:10, treatment == "Drug_A"] + 2
heat_map(
  mat,
  tree = "both",
  tree_cut_x = treatment,
  tree_label_x = TRUE,
  title = "Clustering within groups"
)

Heatmap of 40 simulated genes across 24 samples, with the samples split into labelled Control, Drug_A and Drug_B groups that are each clustered by their own dendrogram under a shared root, and the genes clustered so that those raised in the Drug_A samples sit together at the bottom.

A dendrogram supplied as an hclust or dist object is kept only when the clusters are contiguous in its order, and is dropped with a warning otherwise.

The cluster assignments, row/column order and dendrograms used to construct a heatmap can be extracted from the returned object with heat_map_info():

hm <- heat_map(
  mtcars,
  scale = "column",
  tree_cut_x = 3,
  tree_cut_y = 4,
  popup = FALSE
)
info <- heat_map_info(hm)
info$row_clusters
rownames(mtcars)[info$row_order]

5.2.3 k-means Clusters

For thousands of rows, tree_kmeans_y (or tree_kmeans_x for columns) splits the rows into k-means clusters (Hartigan and Wong 1979) instead of cutting a dendrogram. The rows are clustered on the scaled data from several starts: the centres of equal slices of the rows along their first principal component, which suit clusters strung out along it, and nine k-means++ starts (Arthur and Vassilvitskii 2007), which spread the starting centres over the data so that small clusters get one of their own. The clusters with the smallest within-cluster sum of squares are kept. The starts use fixed seeds, so the same clusters are found every time whatever the random seed, and similar clusters are placed next to each other. The k-means clusters then work like clusters supplied to tree_cut_y: they are separated by splits and can be labelled, and with tree_y = TRUE the rows are clustered within each k-means cluster. heat_map_info()$row_clusters returns the cluster of each row.

set.seed(5)
genes <- matrix(
  rnorm(2000 * 12),
  nrow = 2000,
  dimnames = list(
    paste0("Gene_", 1:2000),
    paste0("S", 1:12)
  )
)
genes[1:400, 1:4] <- genes[1:400, 1:4] + 3
genes[401:800, 5:8] <- genes[401:800, 5:8] + 3
genes[801:1200, 9:12] <- genes[801:1200, 9:12] + 3
heat_map(
  genes,
  scale = "row",
  scale_method = "zscore",
  tree_kmeans_y = 4,
  tree_y = TRUE,
  axis_text_y = NA,
  title = "k-means clusters of 2,000 genes"
)

Row z-scored heatmap of 2,000 simulated genes across 12 samples, split by k-means into four clusters separated by gaps and clustered by a dendrogram within each, in which three clusters are high in samples S9 to S12, S1 to S4 and S5 to S8 respectively and one shows no pattern.

5.3 Group Summaries

heat_map_summarise() reduces the rows (group_y) or columns (group_x) of a dataset to one per group, such as the mean expression of each gene in each cell type, a pseudobulk view of single-cell data. fun chooses the summary: "mean", "median", "sum", "min", "max", "sd", "n", "detected" (the proportion of values above threshold) or a function of your own. Summaries can be combined in a dot plot, with the mean expression as the colour and the proportion of cells in which each gene is detected as the size:

set.seed(6)
types <- c("B cell", "T cell", "NK cell", "Monocyte")
markers <- c("CD19", "MS4A1", "CD3E", "CD4", "NKG7", "GNLY", "CD14", "LYZ")
cell_type <- sample(types, 2000, replace = TRUE)
# Expression of each marker in each cell type
rate <- matrix(runif(32, 0, 0.6), 4, dimnames = list(types, markers))
rate[cbind(rep(types, each = 2), markers)] <- runif(8, 2, 4)
expr <- matrix(
  rpois(2000 * 8, rate[cell_type, ]),
  ncol = 8,
  dimnames = list(NULL, markers)
)
expr <- log1p(expr)
heat_map(
  heat_map_summarise(expr, group_y = cell_type),
  cell_size = heat_map_summarise(expr, group_y = cell_type, fun = "detected"),
  cell_shape = "circle",
  cell_col_scale = "viridis",
  scale = "column",
  scale_method = "zscore",
  legend_title = c("Mean (z-score)", "Detected"),
  title = "Marker genes by cell type"
)

Dot plot of eight marker genes in four simulated cell types, with circles coloured by mean expression (z-scored within each gene) and sized by the proportion of cells in which the gene is detected, so that each cell type has two large bright circles for its own markers.

5.3.1 Distributions Inside Cells

A summary hides the shape of the values behind it. cell_values takes a matrix holding the values behind each cell, such as heat_map_summarise(fun = "values"), and draws their distribution inside the cell: a density with a tick at the median by default, or a histogram or box plot with cell_glyph. Each column shares one range of values (cell_glyph_range), so the curves can be compared down the column. In the example below the “T mixed” cluster has middling CD4 and CD8 medians that look like a dim population; the densities show that it is two populations, one CD4+ and one CD8+.

set.seed(8)
markers <- c("CD3", "CD4", "CD8", "CD19", "CD56", "CD14")
pops <- list(
  "CD4 T" = c("CD3", "CD4"),
  "CD8 T" = c("CD3", "CD8"),
  "T mixed" = "CD3",
  "B" = "CD19",
  "NK" = "CD56",
  "Monocyte" = "CD14"
)
cluster <- sample(names(pops), 6000, replace = TRUE)
events <- matrix(
  rnorm(6000 * 6, 0.5, 0.45),
  ncol = 6,
  dimnames = list(NULL, markers)
)
for (p in names(pops)) {
  ind <- cluster == p
  events[ind, pops[[p]]] <- rnorm(sum(ind) * length(pops[[p]]), 4, 0.55)
}
# Half of the "T mixed" cluster is CD4+, the other half CD8+
mixed <- which(cluster == "T mixed")
cd4 <- mixed[seq_along(mixed) %% 2 == 0]
events[cd4, "CD4"] <- rnorm(length(cd4), 4, 0.55)
cd8 <- setdiff(mixed, cd4)
events[cd8, "CD8"] <- rnorm(length(cd8), 4, 0.55)
heat_map(
  heat_map_summarise(events, group_y = cluster, fun = "median"),
  cell_values = heat_map_summarise(events, group_y = cluster, fun = "values"),
  legend_title = "Median",
  title = "Median intensity, with each cluster's distribution"
)

Heatmap of the median intensity of six markers in six clusters of simulated cytometry events, with a density curve of each cluster's values and a tick at the median drawn inside every cell, showing that the middling CD4 and CD8 medians of the T mixed cluster come from two separate populations.

6. Legends

heat_map() will automatically add legends for the colour scale and size of the cells in the heatmap. The legend argument controls the type(s) of legends to display including "colour", "size", "both" (colour and size) and "levels", a legend for the colours of non-numeric columns, which is drawn by default whenever there are any (legend = "both" leaves it out). The legend is sized from its contents: legend_size scales the legend keys (colour bars, swatches and size legend shapes) and legend_col_scale_size controls the width of the colour scale. The titles and text displayed in the legend(s) are also fully customisable using the legend_title_ and legend_text_ family of arguments.

heat_map(
  mtcars,
  scale = TRUE,
  tree_x = TRUE,
  tree_y = TRUE,
  cell_shape = "circle",
  cell_size = TRUE,
  legend = TRUE,
  legend_size = 1.5,
  legend_col_scale_size = 1.2,
  legend_title = c("colour", "size"),
  title = "Legends"
)

The mtcars heatmap rescaled from 0 to 1 within each column, clustered in both directions and drawn as circles sized and coloured by value, with a colour legend titled colour and a size legend titled size to its right.

Legends can also be drawn below the heatmap with legend_side = "bottom", where the colour bars are horizontal and the legends sit side by side, wrapping into rows when they don’t fit across the figure. The colour scale itself can be shaped in a few ways: cell_col_scale_limits = "robust" uses the 2nd and 98th percentiles of the data so that a few outliers don’t wash out the colours, cell_col_scale_breaks bins the values into a stepped colour scale, and legend_col_breaks chooses the values labelled on the colour legend (names become the labels).

heat_map(
  scale(mtcars),
  tree = "both",
  tree_cut_x = 3,
  cell_col_scale = "Blue-Red 3",
  cell_col_scale_breaks = c(-3, -2, -1, 0, 1, 2, 3),
  legend_col_breaks = c(low = -3, 0, high = 3),
  legend_side = "bottom",
  legend_title = "z-score",
  title = "Legend below the heatmap"
)

The z-scored mtcars heatmap clustered in both directions with the variables cut into three groups, coloured on a stepped blue to red scale whose horizontal legend, labelled low, 0 and high, sits below the heatmap.

legend_col_density = TRUE traces the distribution of the values (a kernel density) over the colour legend, so you can see which colours most cells take and how much of the data sits near the ends of the scale. It is useful with robust limits, where the values beyond the limits all take the end colours.

set.seed(5)
expr <- matrix(
  rnorm(40 * 12),
  nrow = 40,
  dimnames = list(paste0("Gene_", 1:40), paste0("S", 1:12))
)
expr[1:12, 1:6] <- expr[1:12, 1:6] + 1.5
# A few extreme values
expr[sample(length(expr), 9)] <- c(6.5, 7.2, 5.8, 8.1, 6, -5.5, -6.2, 6.8, 5.9)
heat_map(
  expr,
  tree = "both",
  axis_text_y = NA,
  cell_col_scale_limits = "robust",
  legend_col_density = TRUE,
  legend_title = "Expression",
  title = "Robust limits, with the data behind them"
)

Heatmap of 40 simulated genes across 12 samples clustered in both directions, with the colour scale limited to the 2nd and 98th percentiles of the values and a density curve traced over the colour legend showing that most values lie near zero.

6.1 Layout

heat_map() sizes everything around the heatmap in inches from its contents: dendrograms and bar graphs keep the same size whatever the shape of the data (tree_size_x, bar_size_x etc. are multiples of 0.6 inches), the legend is as wide as its text, the margins are as wide as the axis text, axis labels and title, and the heatmap body takes the remaining space. Legends are stacked from the top of the heatmap and shrunk if they don’t fit, and text is shrunk (or thinned) only when it would otherwise overlap. Below, the dendrograms, annotation track and legend are the same size for 60 genes as for 12.

set.seed(3)
mat <- matrix(
  rnorm(60 * 8),
  nrow = 60,
  dimnames = list(
    paste0("Gene_", 1:60),
    paste0("Sample_", 1:8)
  )
)
mat[1:20, 1:4] <- mat[1:20, 1:4] + 2
group <- data.frame(
  Group = rep(c("Control", "Treated"), each = 4),
  row.names = colnames(mat)
)
heat_map_custom(
  popup = TRUE,
  popup_size = c(11, 6.5),
  layout = c(1, 2)
)
heat_map(
  mat,
  tree = "both",
  annotation_x = group,
  legend_title = "Expression",
  title = "60 genes"
)
heat_map(
  mat[1:12, ],
  tree = "both",
  annotation_x = group,
  legend_title = "Expression",
  title = "12 genes"
)
heat_map_complete()

Two clustered heatmaps side by side, of 60 and 12 genes, with dendrograms, annotation tracks and legends of the same size

7. Complex Layouts

HeatmapR supports the arrangement of multiple heatmaps in complex layouts using heat_map_custom(). heat_map_custom() is called prior to plotting to open the appropriate graphics device and set the desired layout before adding the heatmaps. Once the layout is complete, a call is made to heat_map_complete() to reset all heat_map() associated settings. The layout argument can be either a vector indicating the desired number of rows and columns or a matrix defining a more complex layout. For example, if we want to split different car brands into separate heatmaps and arrange them:

heat_map_custom(
  popup = TRUE,
  popup_size = c(10, 15),
  layout = matrix(
    c(1,1,2,2,1,1,3,3),
    ncol = 4,
    nrow = 2,
    byrow = TRUE
  )
)
heat_map(
  mtcars[grepl("Merc", rownames(mtcars)),],
  title = "Mercedes"
)
heat_map(
  mtcars[grepl("Mazda|Toyota", rownames(mtcars)),],
  title = "Mazda | Toyota"
)
heat_map(
  mtcars[grepl("Hornet|Datsun|Volvo", rownames(mtcars)),],
  title = "Hornet | Datsun | Volvo"
)
heat_map_complete()

Three unscaled heatmaps of subsets of the mtcars data arranged in one figure: the Mercedes cars in a large panel on the left, and the Mazda and Toyota cars and the Hornet, Datsun and Volvo cars in two smaller panels on the right, each with its own colour scale.

HeatmapR also supports layouts with other plots generated using base graphics. For example, we could arrange a heatmap with a scatterplot and a boxplot.

heat_map_custom(
  popup = TRUE,
  popup_size = c(10, 15),
  layout = matrix(
    c(1,1,2,2,1,1,3,3),
    ncol = 4,
    nrow = 2,
    byrow = TRUE
  )
)
heat_map(
  mtcars,
  scale = "column",
  cell_size = TRUE,
  legend_size = 1.5,
  title = "mtcars"
)
# heat_map() keeps its margins so that base graphics can be added to the
# heatmap - set them again for the next plots
par(mar = c(5.1, 4.1, 4.1, 2.1))
plot(
  mtcars[, c("disp", "hp")],
  xlab = "Displacement",
  ylab = "Horsepower",
  main = "mtcars: Displacement vs Horsepower",
  pch = 16,
  col = "black"
)
abline(
  lm(hp ~ disp, data = mtcars),
  col = "red",
  lty = 2
)
boxplot(
  mtcars[, "disp"],
  main = "Displacement",
  xlab = "Displacement (cu.in.)",
  horizontal = TRUE
)
heat_map_complete()

A column-scaled mtcars heatmap drawn as squares sized and coloured by value on the left, beside a scatter plot of horsepower against displacement with a dashed red regression line and a horizontal box plot of displacement on the right.

7.1 Heatmaps Beside ggplot2 Plots

heat_map_grob() turns a heatmap into a grid graphical object (a grob), so it can sit beside ggplot2 plots in patchwork, cowplot or gridExtra layouts. The grob draws the heatmap again whenever its space changes, so the dendrograms, legends and text are sized for the space the heatmap is given. Arguments passed to heat_map_grob() replace those the heatmap was drawn with, e.g. heat_map_grob(hm, title = NULL). It needs the gridGraphics package.

library(ggplot2)
library(patchwork)
hm <- heat_map(
  mtcars,
  scale = "column",
  tree = "both",
  tree_cut_y = 3,
  title = "mtcars"
)
p <- ggplot(mtcars, aes(wt, mpg, colour = factor(cyl))) +
  geom_point(size = 2) +
  labs(x = "Weight (1000 lbs)", y = "Miles per gallon", colour = "Cylinders") +
  theme_bw()
p + heat_map_grob(hm) + plot_layout(widths = c(1, 1.5))

A scatter plot of miles per gallon against weight for the mtcars data, coloured by the number of cylinders, beside a clustered heatmap of the same cars

7.2 Heatmap Data for ggplot2 and Other Tools

heat_map_data() returns what a heatmap shows as tidy tables: one row per cell (the default), row, column or dendrogram segment. Rows and columns are listed in the order they are displayed, and x and y are the centres of the cells in the heatmap’s plot co-ordinates, including the gaps between clusters, so the cells can be rebuilt or restyled with ggplot2, exported, or used to draw on the heatmap with base graphics.

cells <- heat_map_data(hm)
rows <- heat_map_data(hm, "rows")
cols <- heat_map_data(hm, "columns")
tree <- heat_map_data(hm, "tree_y")
# Dendrogram to the right of the cells, its heights scaled to 3 cells
edge <- max(cells$x) + 0.5
grow <- function(h) edge + 3 * h / max(tree$x)
ggplot(cells) +
  geom_tile(aes(x, y, fill = value), colour = "white") +
  geom_segment(
    data = tree,
    aes(x = grow(x), y = y, xend = grow(xend), yend = yend)
  ) +
  scale_fill_distiller(palette = "RdBu", name = "Scaled\nvalue") +
  scale_x_continuous(breaks = cols$x, labels = cols$column) +
  scale_y_continuous(breaks = rows$y, labels = rows$row) +
  labs(x = NULL, y = NULL) +
  theme_minimal() +
  theme(
    panel.grid = element_blank(),
    axis.text.x = element_text(angle = 90, hjust = 1, vjust = 0.5)
  )

The mtcars heatmap rebuilt with ggplot2 from heat_map_data(), with a red-blue fill scale, the same row clusters and gaps, and the row dendrogram on the right

Drawn straight after heat_map(), base graphics land on the cells: points(cells$x, cells$y) marks the centre of every cell.

8. Export

HeatmapR supports the export of high resolution images using heat_map_save() which allows control over the dimensions and resolution of the exported image.

heat_map_save(
  "mtcars.png",
  height = 9.5,
  width = 5.7,
  res = 500
)
heat_map(
  mtcars,
  scale = "column",
  scale_method = "range",
  tree_x = TRUE,
  tree_y = TRUE,
  tree_cut_x = 4,
  tree_cut_y = 12,
  cell_size = TRUE,
  cell_shape = "circle",
  title = "mtcars"
)
heat_map_complete()

Heatmap of the mtcars data rescaled within each column, drawn as circles sized and coloured by value, with dendrograms splitting the cars into 12 groups and the variables into 4 groups.

9. Describing a Heatmap

Readers who use screen readers can’t see a heatmap, so figures need alternative text that says what they show. heat_map_describe() writes this description in plain language from the heatmap itself: its size and scaling, what the colours show, the most extreme values, how the rows and columns are clustered and what sets each cluster apart, and any annotations, bars, labels or panels. Pass it to the fig.alt chunk option in R Markdown or Quarto, or use it as a starting point for a figure legend.

hm <- heat_map(
  mtcars,
  scale = "zscore",
  tree = "both",
  tree_cut_y = 3,
  legend_title = "z-score",
  title = "mtcars"
)
heat_map_describe(hm)
Heatmap titled "mtcars" of 32 rows by 11 columns, converted to z-scores within
each column. Colours show z-score, from dark purple (-1.87) through yellow
green to dark red (3.21). The highest value is 3.21 (Maserati Bora, carb) and
the lowest is -1.87 (Ford Pantera L, qsec). Rows are ordered by hierarchical
clustering (euclidean distance, complete linkage). Rows are split into 3
groups, numbered from the top: group 1 (15 rows, e.g. Hornet 4 Drive and
Valiant) is highest in vs and mpg and lowest in cyl and hp; group 2 (12 rows,
e.g. Chrysler Imperial and Cadillac Fleetwood) is highest in disp and cyl and
lowest in gear and drat; group 3 (5 rows, e.g. Ferrari Dino and Mazda RX4) is
highest in carb and gear and lowest in qsec and vs. Columns are ordered by
hierarchical clustering (euclidean distance, complete linkage).

In a chunk that draws the heatmap, compute the description in an earlier chunk and refer to it, e.g. fig.alt = as.character(heat_map_describe(hm)). Clusters are described by the columns in which their mean is highest and lowest (rows, for clusters of columns), and max_groups limits how many clusters are described one by one.

10. Summary

HeatmapR is a lightweight R package built on base graphics that allows for the creation of high resolution complex heatmaps that can be arranged in sophisticated layouts with other plot objects.

References

Arthur, D. and Vassilvitskii, S. (2007). k-means++: the advantages of careful seeding. Proceedings of the 18th Annual ACM-SIAM Symposium on Discrete Algorithms (SODA ’07), 1027-1035.

Atkins, J. E., Boman, E. G. and Hendrickson, B. (1998). A spectral algorithm for seriation and the consecutive ones problem. SIAM Journal on Computing, 28(1), 297-310. doi:10.1137/S0097539795285771

Bar-Joseph, Z., Gifford, D. K. and Jaakkola, T. S. (2001). Fast optimal leaf ordering for hierarchical clustering. Bioinformatics, 17(suppl 1), S22-S29. doi:10.1093/bioinformatics/17.suppl_1.S22

Bendall, S. C. et al. (2011). Single-cell mass cytometry of differential immune and drug responses across a human hematopoietic continuum. Science, 332(6030), 687-696. doi:10.1126/science.1198704

Correll, M., Moritz, D. and Heer, J. (2018). Value-suppressing uncertainty palettes. Proceedings of the 2018 CHI Conference on Human Factors in Computing Systems. doi:10.1145/3173574.3174216

Croes, G. A. (1958). A method for solving traveling-salesman problems. Operations Research, 6(6), 791-812. doi:10.1287/opre.6.6.791

Felsenstein, J. (1985). Confidence limits on phylogenies: an approach using the bootstrap. Evolution, 39(4), 783-791. doi:10.1111/j.1558-5646.1985.tb00420.x

Fiedler, M. (1973). Algebraic connectivity of graphs. Czechoslovak Mathematical Journal, 23(2), 298-305. doi:10.21136/CMJ.1973.101168

Hartigan, J. A. and Wong, M. A. (1979). Algorithm AS 136: a k-means clustering algorithm. Applied Statistics, 28(1), 100-108. doi:10.2307/2346830

Hintze, J. L. and Nelson, R. D. (1998). Violin plots: a box plot-density trace synergism. The American Statistician, 52(2), 181-184. doi:10.1080/00031305.1998.10480559

Kaufman, L. and Rousseeuw, P. J. (1990). Finding Groups in Data: An Introduction to Cluster Analysis. Wiley. doi:10.1002/9780470316801

Müllner, D. (2011). Modern hierarchical, agglomerative clustering algorithms. arXiv:1109.2378. doi:10.48550/arXiv.1109.2378

Murdoch, D. J. and Chow, E. D. (1996). A graphical display of large correlation matrices. The American Statistician, 50(2), 178-180.

Murtagh, F. (1983). A survey of recent advances in hierarchical clustering algorithms. The Computer Journal, 26(4), 354-359. doi:10.1093/comjnl/26.4.354

Rousseeuw, P. J. (1987). Silhouettes: a graphical aid to the interpretation and validation of cluster analysis. Journal of Computational and Applied Mathematics, 20, 53-65. doi:10.1016/0377-0427(87)90125-7

Shi, J. and Malik, J. (2000). Normalized cuts and image segmentation. IEEE Transactions on Pattern Analysis and Machine Intelligence, 22(8), 888-905. doi:10.1109/34.868688