Clustered heatmap with dendrograms — clustermap • plotomics

A hierarchically-clustered expression heatmap (in the spirit of seaborn.clustermap / Morpheus): the matrix is drawn on a GPU/canvas data layer so large matrices stay smooth, while dendrograms, tick labels and the colorbar are crisp vector overlays. Rows and columns are agglomeratively clustered and reordered so structure appears as blocks along the diagonal.

Usage

clustermap(
  mat,
  metric = c("euclidean", "correlation"),
  linkage = c("average", "complete", "ward"),
  colormap = c("viridis", "rdbu"),
  z_score = FALSE,
  cluster_rows = TRUE,
  cluster_cols = TRUE,
  show_row_dendrogram = TRUE,
  show_col_dendrogram = TRUE,
  show_labels = TRUE,
  legend_title = "value",
  row_linkage = NULL,
  col_linkage = NULL,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL
)

Arguments

mat: A numeric matrix. Row and column names, if present, are used as labels. Values are transported row-major to the browser.
metric: Distance metric for clustering: "euclidean" or "correlation" (1 - Pearson correlation).
linkage: Agglomeration method: "average", "complete" or "ward".
colormap: Color ramp: "viridis" (sequential) or "rdbu" (diverging).
z_score: Standardize each row to mean 0 / sd 1 before coloring.
cluster_rows, cluster_cols: Cluster and reorder rows / columns. Ignored for an axis when a precomputed row_linkage / col_linkage is supplied.
show_row_dendrogram, show_col_dendrogram: Draw the row / column dendrogram.
show_labels: Draw row/column tick labels (auto-hidden when cells get too small to be legible).
legend_title: Colorbar legend title.
row_linkage, col_linkage: Optional precomputed leaf order or dendrogram to skip clustering that axis. Either an integer vector giving the 0-based leaf order, or a list with order (0-based) and merges (each a list with left, right, height; leaves are 0..n-1, internal node k is n + k).
theme: Optional named list of theme overrides (colors, fonts, ...) merged over the component defaults in the browser. NULL uses the default theme.
width, height: Widget dimensions (any valid CSS size).
element_id: Optional explicit DOM id.

Value

An htmlwidget object.

Details

Clustering is at least O(n^2) in the number of rows/columns (it builds a full distance matrix), so clustermap() only clusters automatically when a dimension has at most 2000 leaves. For larger matrices, precompute a leaf order (or a dendrogram) elsewhere and pass it via row_linkage / col_linkage to skip clustering; the heatmap rendering itself scales to much larger matrices.

Examples

set.seed(1)
# Two clear blocks of correlated genes across two groups of samples.
mat <- rbind(
  matrix(rnorm(20 * 10, mean = 2), nrow = 20),
  matrix(rnorm(20 * 10, mean = -2), nrow = 20)
)
rownames(mat) <- paste0("gene", seq_len(nrow(mat)))
colnames(mat) <- paste0("s", seq_len(ncol(mat)))
clustermap(mat, colormap = "rdbu", z_score = TRUE)