Skip to contents

Dendrogram ggplot2 theme

Source: R/theme_dendro.R
theme_dendro.Rd

A minimal theme designed for dendrogram plots created with dendextend and ggplot2. Two visual styles are available: "solaris" (cream background, warm accents) and "t2m" (white background, clean and minimal).

Usage

theme_dendro(
  style,
  base_size,
  base_family,
  horiz = NULL,
  medium,
  label_size = 7,
  proportion = NULL,
  cluster = NULL,
  recolor,
  height_title = NULL,
  title = NULL,
  label_padding = 0.8,
  label_gap = 0.02,
  grid_lines = FALSE,
  corner_radius = 3,
  cluster_alpha = 0.2,
  cluster_linetype = "dashed",
  branch_width = NULL
)

Arguments

style

Character. Visual style: "solaris" (default) for the cream-background warm theme, or "t2m" for the white-background minimal theme. Defaults to the style set by set_theme; falls back to "solaris" if no theme has been set.

base_size

Numeric. Base font size in points. Defaults to the size set by set_theme; falls back to 18.

base_family

Character. Base font family. Defaults to the family set by set_theme; falls back to "sans".

horiz

Logical or NULL (default). Dendrogram orientation. If NULL (default), auto-detects from the plot: checks for coord_flip (used by dendextend for horizontal dendrograms), falling back to FALSE (vertical). Pass TRUE for horizontal dendrograms (leaf labels on the y-axis, height on the x-axis) or FALSE for vertical dendrograms (leaf labels on the x-axis, height on the y-axis).

medium

Character. Output medium: "screen" (default) for presentations and PDF viewing, or "print" for physical printing with heavier lines and darker text. Defaults to the medium set by set_theme; falls back to "screen".

label_size

Numeric. Font size for leaf labels in points (default 7). Dendextend sets leaf labels to size 5 by default; this parameter overrides that value.

proportion

Numeric or NULL (default). The fraction of the dendrogram height to offset leaf labels away from branch tips. If NULL (default), the proportion is computed automatically from the maximum label length and font size. Supply a numeric value to override the automatic calculation.

cluster

Controls cluster rectangle behaviour. One of:

NULL (default)

auto-detect cluster rectangles from the plot's segment colours. If the dendrogram has coloured branches (e.g. from set("branches_k_color")), rectangles are drawn around each colour group. If no coloured segments are found, no rectangles are drawn.

FALSE

explicitly suppress cluster rectangles, even if the dendrogram has coloured branches.

list(dend = ..., k = ...)

draw rectangles for k clusters using the supplied dendrogram object.

list(dend = ...)

auto-detect k from the dendrogram's branch colours; if no colours are found, no rectangles are drawn.

When a list is supplied, it may also contain: gap (default 0.1), padding (default 0.25), label_gap (default 0.02), ymin, ymax, linetype (default "dashed"), linewidth (default 0.3), alpha (default 0.2), and mapping. Border and fill colours are set automatically from style.

recolor

Logical. When TRUE (default), replace dendextend's default branch colours with the ggastrum palette matching style: solaris_pal for "solaris" or viridis_pal for "t2m". Set to FALSE to keep whatever colours dendextend (or the user) assigned. Defaults to the recolor option set by set_theme; falls back to TRUE.

height_title

Character or NULL (default). Label for the height axis. If NULL (default), no axis title is shown. Set to a string (e.g. "Height") to display a bold axis title on the height axis. For horizontal dendrograms the title appears on the x-axis; for vertical dendrograms on the y-axis.

title

Character or NULL (default). Plot title. If NULL (default), no title is shown. Set to a string to display a bold title above the plot.

label_padding

Numeric padding (in data units) added above and below the leaf-label axis. Default 0.8. Set to 0 for no extra padding, or increase for more breathing room between labels and the plot edge.

label_gap

Numeric. Proportional vertical offset between the leaf labels and the bottom edge of cluster rectangles, expressed as a fraction of the dendrogram height. Default 0.02. Increase for more space between labels and rectangles; decrease to bring rectangles closer to the labels.

grid_lines

Logical. When TRUE, draw faint gridlines along the height axis. Default FALSE (no gridlines). For horizontal dendrograms the gridlines are vertical; for vertical dendrograms they are horizontal.

corner_radius

Numeric. Corner radius (in points) for cluster rectangles. Default 3 (subtly rounded corners). Set to 0 for sharp corners or a larger number for more rounding.

cluster_alpha

Numeric. Fill alpha for cluster rectangles. Default 0.2. Also available inside the cluster list as alpha; this parameter takes precedence when set.

cluster_linetype

Character or integer. Line type for cluster rectangle borders. Default "dashed". Also available inside the cluster list; this parameter takes precedence when set.

branch_width

Numeric or NULL (default). When non-NULL, override the dendextend branch line width for all segment layers. Useful for making branches thicker or thinner. NULL keeps the dendextend default.

Value

When horiz = NULL (default), an object of class "theme_dendro_autodetect" that resolves at + time. When horiz is explicitly TRUE or FALSE, the built theme with class "theme_dendro_explicit". Both classes automatically offset leaf labels away from branch tips and add the appropriate y-scale expansion so labels are not clipped. When proportion = NULL (default), the offset is computed dynamically from label length; supply a numeric value to override. When cluster is provided, cluster rectangles are added as a layer with colours matched to style. If k is omitted, it is auto-detected from the dendrogram's branch colours; if no colours are found, no rectangles are drawn. When cluster is NULL (default), rectangles are auto-detected from the plot's segment colours; when FALSE, rectangles are suppressed entirely. If a scale_y_*() call is added after theme_dendro(), it replaces the theme-provided scale, giving the user full control.

Details

When added to a plot with +, theme_dendro() auto-detects whether the plot uses coord_flip (as dendextend does for horizontal dendrograms) and sets the height axis accordingly. Pass horiz = TRUE or horiz = FALSE to override auto-detection.

The theme starts from theme_gray and blanks out all grid lines, panels, and the leaf-label axis, keeping only the height axis with line, ticks, and text. Set height_title to label the height axis.

The height axis is automatically truncated at zero and the maximum merge height, removing excess padding above the tree.

See also

theme_solaris, theme_t2m, set_theme

Author

Dustin Stoltz

Examples

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

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

# Horizontal dendrogram — rectangles auto-detected from branch colours
dendro_ggplot(ggd, horiz = TRUE) +
  theme_dendro(height_title = "Height")

# Vertical dendrogram — explicit orientation
dendro_ggplot(ggd, horiz = FALSE) +
  theme_dendro(horiz = FALSE, height_title = "Height")

# t2m style
dendro_ggplot(ggd, horiz = TRUE) +
  theme_dendro(style = "t2m", height_title = "Height")

# Cluster rectangles via the cluster parameter (explicit k)
dendro_ggplot(ggd, horiz = TRUE) +
  theme_dendro(cluster = list(dend = dend, k = 3), height_title = "Height")

# Suppress auto-detected rectangles
dendro_ggplot(ggd, horiz = TRUE) +
  theme_dendro(cluster = FALSE, height_title = "Height")
} # }