Skip to contents

Combine dendrogram and alluvial plot with alignment and flexible legend placement

Source: R/dendrogram.r
combine_dendrogram_alluvial.Rd

Compose a dendrogram panel and an alluvial panel into one figure with stable alignment. Supports vertical stacking (top/bottom) and horizontal composition (left/right).

Usage

combine_dendrogram_alluvial(
  alluvial_plot,
  dendrogram_plot,
  dend_position = c("top", "bottom", "left", "right"),
  dend_height = 0.15,
  strip_alluvial_x = TRUE,
  legend = c("separate", "omit", "together"),
  legend_source = c("alluvial", "dendrogram", "both"),
  legend_position = c("right", "bottom"),
  legend_rel_width = 0.28,
  legend_rel_height = 0.18,
  alluvial_margins = ggplot2::margin(0, 0, 0, 0),
  dendrogram_margins = ggplot2::margin(0, 0, 0, 0),
  outer_margins = ggplot2::margin(0, 0, 0, 0),
  alluvial_legend_overrides = NULL,
  dendrogram_legend_overrides = NULL,
  legend_box = c("vertical", "horizontal"),
  align = c("panel", "full_grob"),
  x_expand_zero = FALSE,
  leaf_order = NULL,
  align_x_centers = FALSE,
  overwrite_x_scales = FALSE,
  x_labels = NULL,
  x_drop = FALSE,
  dend_limits_left = 0.5,
  dend_limits_right = 0.5,
  align_y_centers = FALSE,
  overwrite_y_scales = FALSE,
  dend_limits_bottom = 0.5,
  dend_limits_top = 0.5
)

Arguments

alluvial_plot

A plain ggplot (alluvial panel). Must not be an aplot composite.

dendrogram_plot

A plain ggplot (dendrogram panel). Must not be an aplot composite.

dend_position

"top","bottom","left","right". Default "top".

dend_height

Relative size of dendrogram panel. For top/bottom = fraction of height; for left/right = fraction of width. Default 0.15.

strip_alluvial_x

If TRUE, remove alluvial x axis title/text/ticks (useful for top/bottom stacks).

legend

"separate","omit","together"

legend_source

"alluvial","dendrogram","both"

legend_position

"right","bottom" (only used when legend="separate")

legend_rel_width

Relative legend column width (legend_position="right")

legend_rel_height

Relative legend row height (legend_position="bottom")

alluvial_margins

Plot margin for alluvial panel (ggplot2::margin()).

dendrogram_margins

Plot margin for dendrogram panel (ggplot2::margin()).

outer_margins

Outer margin around full grob. Accepts ggplot2::margin(), unit length, or numeric c(t,r,b,l) in pt.

alluvial_legend_overrides

Optional list of ggplot additions applied only during legend extraction.

dendrogram_legend_overrides

Optional list of ggplot additions applied only during legend extraction.

legend_box

"vertical" or "horizontal" when legend_source="both".

align

"panel" (recommended) or "full_grob". "panel" equalizes only the panel region; "full_grob" uses unit.pmax on all slots.

x_expand_zero

If TRUE, set expand=0 on x scales where no x scale is defined yet.

leaf_order

Character vector giving leaf order. If NULL, uses attr(dendrogram_plot,"leaf_order").

align_x_centers

For top/bottom: lock x-centers between dend tips and alluvial strata. Uses scale_x_discrete(limits=leaf_order) on alluvial, and coord_cartesian(xlim=...) on dendrogram.

overwrite_x_scales

If TRUE, overwrite existing x scales when applying align_x_centers.

x_labels

Optional relabeling for the alluvial x axis when align_x_centers = TRUE. Does not change the underlying factor levels used for alignment. Accepts:

  • A named character vector mapping leaf_order values (e.g. Bio_SampleID) to display labels.

  • A function passed to scale_x_discrete(labels = ...).

If NULL (default), original x scale labels are used. When overwrite_x_scales = TRUE, any existing x scale on the alluvial plot will be replaced and x_labels will be applied.

x_drop

Logical; passed to scale_x_discrete(drop = ...) when enforcing alignment with leaf_order. Default FALSE. Set to TRUE to drop unused factor levels.

dend_limits_left, dend_limits_right

“sweet spot” for dendrogram x view: dend xlim = c(dend_limits_left, n + dend_limits_right). Use e.g. -0.75 and 0.2.

align_y_centers

For left/right: lock y-centers. Intended for dendrogram plotted with plot_dendrogram(orientation="left"/"right") and alluvial with coord_flip(). IMPORTANT: even with coord_flip(), group order is still controlled by scale_x_discrete on alluvial. Uses coord_cartesian(ylim=...) on dendrogram to avoid dropping segments.

overwrite_y_scales

If TRUE, overwrite existing scales used for align_y_centers.

dend_limits_bottom, dend_limits_top

“sweet spot” for dendrogram y view: dend ylim = c(dend_limits_bottom, n + dend_limits_top).

#' @details When align_x_centers = TRUE, the function enforces identical x positions between dendrogram tips and alluvial strata using leaf_order. The underlying factor levels are not modified. Use x_labels to change only the displayed axis text (e.g. mapping Bio_SampleID to Subsite_BID) without breaking alignment. To place the dendrogram ideally above the alluvial plot (leaves in the centre of bars) try different combinations of dend_limits_left,dend_limits_right or dend_limits_bottom,dend_limits_top.

Value

A grob (gridExtra::arrangeGrob) suitable for ggsave().