Cluster rectangles for dendrograms — dendro_cluster

Creates geom_rect layers that draw rectangular boxes around leaf clusters in a dendrogram. Works with both horizontal and vertical orientations produced by dendextend.

Usage

dendro_cluster_rects(
  dend,
  k,
  gap = 0.1,
  padding = 0.25,
  label_gap = 0.02,
  ymin = NULL,
  ymax = NULL,
  style = c("solaris", "t2m"),
  linetype = "dashed",
  linewidth = 0.3,
  alpha = 0.2,
  mapping = NULL,
  ...
)

Arguments

dend: A dendrogram object.
k: Integer. Number of clusters. The dendrogram is cut at the height that produces k subtrees; each subtree defines one cluster rectangle.
gap: Numeric. Space between adjacent cluster rectangles (default 0.1).
padding: Numeric. Padding on the outer edges of the first and last cluster rectangle (default 0.25).
label_gap: Numeric. Proportional distance to shift rectangles away from leaf labels along the height axis, expressed as a fraction of the dendrogram height (default 0.02). Both ymin and ymax are shifted by this proportion of the height, creating a visual gap between the label text and the rectangle border.
ymin: Numeric or NULL. Lower y-bound for rectangles. When NULL (default), computed as -max_height * proportion + max_height * label_gap, where proportion is automatically calculated from the longest leaf label to prevent clipping.
ymax: Numeric or NULL. Upper y-bound for rectangles. When NULL (default), computed as max_height * proportion * 2 + max_height * label_gap.
style: Character. Visual style: "solaris" (default) for warm-toned borders and fill, or "t2m" for cool-toned borders and fill.
linetype: Character or integer. Line type for rectangle borders (default "dashed").
linewidth: Numeric. Line width for rectangle borders (default 0.3).
alpha: Numeric. Fill opacity (default 0.2).
mapping: An aes mapping to override or supplement defaults. Use aes(fill = factor(cluster)) to colour rectangles by cluster.
...: Additional arguments passed to geom_rect.

Value

A dendro_cluster_rects object (with a ggplot_add method) that can be added to a ggplot2 plot built from a dendextend ggdend object.

Details

Clusters are determined by cutting the dendrogram at the height that produces k subtrees. Each subtree corresponds to one visually contiguous group in the dendrogram, so the resulting rectangles never overlap and there are exactly k of them.

The data frame inside the layer includes a cluster column that can be mapped to aesthetics via the mapping argument:


  dendro_cluster_rects(dend, k = 3,
    mapping = aes(fill = factor(cluster)))

The default colours are theme-aware. style = "solaris" uses warm grays that blend with the cream background; style = "t2m" uses darker grays suited to the white background.

The rectangle bounds are computed in data coordinates:

xmin/xmax: boundaries are placed at midpoints between adjacent clusters, with gap spacing on each side. The first and last clusters receive padding on their outer edges.
ymin/ymax: both shifted by label_gap away from the leaf labels, creating a gap between the label text and the rectangle border.

Because dendextend applies coord_flip() + scale_y_reverse() for horizontal dendrograms, the same rectangle data works for both orientations.

Author

Dustin Stoltz

Examples

if (FALSE) { # \dontrun{
library(ggplot2)
suppressPackageStartupMessages(library(dendextend))

hc <- hclust(dist(USArrests[1:10, ]))
dend <- as.dendrogram(hc) |>
  set("branches_k_color", k = 3) |>
  set("branches_lwd", 1.5)
ggd <- as.ggdend(dend)

# Horizontal with cluster rectangles
dendro_ggplot(ggd, horiz = TRUE) +
  dendro_cluster_rects(dend, k = 3) +
  theme_dendro() +
  labs(y = "Height")

# Per-cluster fill colours
dendro_ggplot(ggd, horiz = TRUE) +
  dendro_cluster_rects(dend, k = 3,
    mapping = aes(fill = factor(cluster))) +
  theme_dendro() +
  labs(y = "Height")

# t2m style
dendro_ggplot(ggd, horiz = TRUE) +
  theme_dendro(style = "t2m") +
  dendro_cluster_rects(dend, k = 3, style = "t2m") +
  labs(y = "Height")
} # }