Skip to contents

Draw a Heatmap

Source: R/draw.R
draw_heatmap.Rd

Quick heatmap from a numeric matrix. Designed to handle all common use cases including correlation matrices (square cells, diverging color scale), general rectangular heatmaps, and clustered heatmaps.

Usage

draw_heatmap(
  x,
  row_names = NULL,
  col_names = NULL,
  triangle = NULL,
  cluster_rows = FALSE,
  cluster_cols = FALSE,
  dist_method = "euclidean",
  hclust_method = "complete",
  show_row_dendro = TRUE,
  show_col_dendro = TRUE,
  dendro_row_width = 60,
  dendro_col_height = 60,
  dendro_color = NULL,
  dendro_uniform = FALSE,
  dendro_row_side = "right",
  dendro_col_side = "top",
  square_cells = NULL,
  colormap = NULL,
  zlim = NULL,
  show_values = FALSE,
  value_digits = 2L,
  show_colorbar = TRUE,
  colorbar_orient = "vertical",
  title = NULL,
  theme = NULL,
  margins = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL,
  legend_position = if (colorbar_orient == "horizontal") "bottom" else "right",
  legend_placement = "outside",
  row_tree = NULL,
  col_tree = NULL,
  cell_notes = NULL,
  row_colors = NULL,
  col_colors = NULL,
  show_notes = FALSE,
  row_cut = NULL,
  col_cut = NULL
)

Arguments

x

Numeric matrix: Input data. Rows map to y-axis categories and columns to x-axis categories.

row_names

Optional Character: Row labels. Defaults to rownames(x), or "1", "2", ... when row names are absent.

col_names

Optional Character: Column labels. Defaults to colnames(x).

triangle

Optional Character {"upper", "lower"}: Mask one triangle of the matrix to NA. "upper" keeps only the upper triangle; "lower" keeps only the lower triangle. The diagonal is always masked, as it is uninformative for symmetric matrices (e.g. always 1 for correlations).

cluster_rows

Logical: Whether to reorder rows via hierarchical clustering.

cluster_cols

Logical: Whether to reorder columns via hierarchical clustering.

dist_method

Character: Distance method passed to stats::dist(). Common values: "euclidean", "manhattan".

hclust_method

Character: Linkage method passed to stats::hclust(). Common values: "complete", "ward.D2", "average".

show_row_dendro

Logical: Whether to render the row dendrogram panel when cluster_rows = TRUE. Set to FALSE to reorder rows but suppress the visual dendrogram.

show_col_dendro

Logical: Whether to render the col dendrogram panel when cluster_cols = TRUE.

dendro_row_width

Optional Numeric [1, Inf): Pixel width of the row dendrogram panel (between row labels and the heatmap grid).

dendro_col_height

Optional Numeric [1, Inf): Pixel height of the col dendrogram panel (between the chart title and the heatmap grid).

dendro_color

Optional Character: Stroke color for dendrogram branch lines. NULL (default) uses a semi-transparent gray ("#99999988"), which works in both light and dark themes.

dendro_uniform

Logical: Whether to render dendrograms with uniform level heights — each merge step occupies equal visual space — rather than heights proportional to actual merge distances. FALSE (default) preserves merge distances in the visual scaling.

dendro_row_side

Character {"right", "left"}: Side of the heatmap on which the row dendrogram is placed. "right" (default) keeps row labels on the left with the dendrogram on the right for a clean, symmetric layout.

dendro_col_side

Character {"top", "bottom"}: Side of the heatmap on which the column dendrogram is placed. "top" (default) places it above the heatmap. "bottom" automatically moves column labels to the top.

square_cells

Optional Logical: Whether to compute widget dimensions so cells are square in the browser and SVG exports. In panels and exports, the matrix and dendrograms fit within the allocated canvas. NULL (default) enables this automatically for square matrices (e.g. correlation matrices). When TRUE, both width and height are calculated from the number of cells; supply explicit width/height to override.

colormap

Optional Character: Color palette — a vector of 2 or more colors defining the continuous color scale from zlim[1] to zlim[2]. When NULL (default) a diverging teal–background–orange palette is used when data spans zero (with the background color pinned exactly at 0, even for asymmetric ranges), otherwise a sequential single-hue palette is used. Two variants (light / dark) are computed automatically and the JS binding selects the correct one based on the active theme.

zlim

Optional Numeric: Length-2 vector c(min, max) for the color scale. Defaults to the observed data range. For correlation matrices, c(-1, 1) is recommended.

show_values

Logical: Whether to print the cell value as a label inside each cell.

value_digits

Integer: Decimal places used in cell labels and the tooltip.

show_colorbar

Logical: Whether to display the continuous color-scale bar.

colorbar_orient

Character {"vertical", "horizontal"}: Orientation of the color bar.

title

Optional Character: Chart title.

theme

Optional Theme: Theme override. NULL auto-detects light/dark mode.

margins

Optional Named numeric vector or named list: Override the auto-computed heatmap plot-area margins in pixels (or percentage strings) for any of "top", "right", "bottom", "left" — e.g. c(left = 200) to widen the left gutter for long row labels. Unspecified sides use the values computed from label lengths, title, colorbar, and dendrogram panels. See draw_line() for the general convention.

width

Optional Character or Numeric: Widget width.

height

Optional Character or Numeric: Widget height.

element_id

Optional Character: Explicit DOM element ID for the widget container. NULL lets htmlwidgets generate one.

filename

Optional Character: If provided, save the widget to this file via save_drawing().

legend_position

Character {"top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"}: Legend anchor. Top/bottom anchors use horizontal rows; left/right anchors use a vertical column. Corner anchors align within the top or bottom row.

legend_placement

Character {"outside", "inside"}: Relation to the plotting area. Outside placement reserves space for the complete legend; inside placement overlays the data. Neither setting adds a missing legend.

row_tree, col_tree

Optional hclust, dendrogram or List: Supplied trees. A plain tree record contains merge, height, order and optional labels. Labeled leaves match original matrix dimnames; unlabeled trees are positional. Supplied trees determine order and take precedence over computed clustering. Triangle masking is unavailable with supplied trees.

cell_notes

Optional Character matrix: Literal cell notes for hover. Named dimensions align to original matrix identities; otherwise positional.

row_colors, col_colors

Optional Character vector, matrix or Data frame: R colors, one row per matrix row/column and one column per annotation track. Row names, when supplied, match the original matrix identities.

show_notes

Logical: Print cell notes instead of numeric value labels. Long notes truncate to the cell width; hover retains the full text.

row_cut, col_cut

Optional Integer: Number of clusters for branch coloring. A cut requires a supplied or computed tree. Cross-cluster branches stay gray (or dendro_color); within-cluster branches share a deterministic color.

Value

htmlwidget: Widget object.

Details

Color encoding is driven by a continuous VisualMap component. Hierarchical clustering is performed in R via hclust(); rows and columns are reordered accordingly. When cluster_rows or cluster_cols is TRUE (and the corresponding show_*_dendro flag is not FALSE), a dendrogram panel is rendered alongside the heatmap as an ECharts custom series.

Examples

draw_heatmap(cor(mtcars[, 1:5]), title = "Correlation")