Draw a Heatmap — draw_heatmap • rtemis.draw

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,
  color = 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,
  filename = 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 grey ("#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. 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.
color: 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 colour 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.
filename: Optional Character: If provided, save the widget to this file via save_drawing().

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.