Skip to contents

Parallel Sets (Alluvial) Plot

PlotAlluvial.Rd

Creates a parallel sets (alluvial) chart - a clean alternative to SCP's alluvials that preserves your own color palettes and theme.

Supports two or more axes via the axes parameter. Passing three or more columns (e.g. axes = c("BraakStage", "ThalPhase", "CERAD")) produces a multi-axis diagram ideal for multiparametric comparisons.

Use donor.by to aggregate to the donor / patient level before computing counts - streams then show donor flows rather than cell flows. This is the recommended approach for neuropathology scores, clinical metadata, or any variable that is defined per-individual rather than per-cell.

When facet.by is supplied, one alluvial panel is drawn per level and assembled with patchwork. Plot margins are auto-expanded based on the longest axis label so text is never clipped.

Usage

PlotAlluvial(
  data,
  axes = NULL,
  group.by = NULL,
  split.by = NULL,
  donor.by = NULL,
  facet.by = NULL,
  ncol_facet = NULL,
  alpha = 0.75,
  axis_width = 0.1,
  label = TRUE,
  label_size = 4,
  label_nudge = 0.1,
  group_colors = NULL,
  split_colors = NULL,
  axes_colors = list(),
  axis.labels = NULL,
  facet.spacing = 1,
  horizontal = FALSE,
  label.inside = FALSE,
  title.size = 13,
  title.rotation = 0,
  output_dir = NULL,
  object_name = "",
  pdf_width = 7,
  pdf_height = 5.5
)

Arguments

data

A Seurat object or a plain data.frame/tibble containing the metadata columns.

axes

Character vector of 2 or more column names to use as axes, from left to right (e.g. c("BraakStage", "ThalPhase", "CERAD")). Stream color is determined by the first axis.

group.by

Character. Left-axis column (retained for backwards compatibility). Ignored when axes is supplied.

split.by

Character. Right-axis column (retained for backwards compatibility). Ignored when axes is supplied.

donor.by

Character or NULL. Metadata column identifying the donor / patient (e.g. "Donor.ID"). When supplied, metadata is first deduplicated to one row per donor so stream widths reflect donor counts rather than cell counts - the right choice for patient-level pathological scores (BraakStage, Thal phase, CERAD, etc.). Default NULL.

facet.by

Character or NULL. Metadata column to facet by - one alluvial panel per level (e.g. "Diagnosis"). Default NULL.

ncol_facet

Integer or NULL. Number of panel columns when facet.by is used. Auto-computed (max 3) if NULL.

alpha

Numeric. Stream transparency. Default 0.75.

axis_width

Numeric. Width of the axis rectangles. The stream width is 1.5 × axis_width. Default 0.1.

label

Logical. Annotate each axis segment with its level name. Default TRUE.

label_size

Numeric. Label font size. Default 4.

label_nudge

Numeric. Horizontal gap between axis bar and label. Default 0.1.

group_colors

Named character vector of colors for the first axis (streams + left axis). Auto-assigned if NULL.

split_colors

Named character vector of colors for the last axis. Auto-assigned if NULL.

axes_colors

Named list of color vectors, keyed by column name (e.g. list(BraakStage = BraakColors, ThalPhase = ThalColors)). Takes precedence over group_colors/split_colors.

axis.labels

Character vector of display labels for the axes, in the same order as axes. Use this to show short/readable names instead of raw column names (e.g. c("AD neuropath.", "Cognitive status", "Dementia")). NULL = use column names as-is.

facet.spacing

Numeric (0-1+). Scale factor applied to the auto-computed left and right panel margins when facet.by is used. Values below 1 shrink the gap between panels (try 0.5); values above 1 widen it. Default 1 (no change).

horizontal

Logical. If TRUE, rotate the diagram 90 degrees so axis bars run horizontally using coord_flip(). Best combined with label.inside = TRUE. Default FALSE.

label.inside

Logical. If TRUE, place category labels centered inside the colored bars in white text instead of outside. Default FALSE.

title.size

Numeric. Font size for the axis name labels (e.g. "Sex", "Group"). Default 13.

title.rotation

Numeric. Rotation angle (degrees) for the axis name labels. Default 0 (horizontal).

output_dir

Directory to save a PDF. NULL = no save.

object_name

Label prefix for the output filename.

pdf_width, pdf_height

PDF dimensions per panel in inches. Default 7 x 5.5.

Value

A ggplot2 or patchwork object (invisibly).