Skip to contents

Chord Diagram Across Two or More Categorical Variables

PlotChord.Rd

Draws a chord diagram showing connectivity across two or more metadata variables (e.g. cell type, diagnosis, sex). Arc widths are proportional to cell (or donor) counts. Uses circlize.

With two variables the diagram is a standard bidirectional chord between the two sector sets. With three or more variables, adjacent pairs are linked in sequence (A-B, B-C, ...) so the diagram reads like a circular alluvial: sectors are grouped by variable around the circle and chords only connect adjacent variables. Sector labels show the level name only (the variable prefix is used internally to keep names unique but is stripped in the plot).

Because circlize draws to the active graphics device (base R graphics), this function returns the link object invisibly rather than a ggplot2 object.

Usage

PlotChord(
  data,
  variables = NULL,
  var1 = NULL,
  var2 = NULL,
  donor.by = NULL,
  facet.by = NULL,
  ncol_facet = NULL,
  canvas_padding = 0.3,
  colors = NULL,
  var1_colors = NULL,
  var2_colors = NULL,
  group.gap = 15,
  sector.gap = 2,
  alpha = 0.8,
  label_cex = 0.8,
  directional = FALSE,
  output_dir = NULL,
  object_name = "",
  pdf_width = 7,
  pdf_height = 7
)

Arguments

data

A Seurat object or a plain data.frame/tibble.

variables

Character vector of two or more metadata column names, in the order they should appear around the chord circle.

var1, var2

Deprecated aliases kept for backward compatibility. Use variables instead.

donor.by

Character or NULL. Column identifying the donor / patient. When supplied, metadata is deduplicated to one row per donor so arc widths reflect donor counts. Default NULL.

facet.by

Character or NULL. Metadata column to facet by - one chord diagram per level, arranged side-by-side in a grid.

ncol_facet

Integer or NULL. Columns in the facet grid. Auto-computed (max 3) if NULL.

canvas_padding

Numeric. Extra space around the chord circle to prevent label clipping. Default 0.3.

colors

Named list of color vectors, one element per variable name (e.g. list(CellType = c(...), Diagnosis = c(...))). Auto-assigned if NULL.

var1_colors, var2_colors

Deprecated. Use colors instead.

group.gap

Numeric. Gap in degrees between variables[1] sectors and variables[2] sectors on the chord circle. Default 15.

sector.gap

Numeric. Gap in degrees between individual sectors within each variable. Default 2.

alpha

Numeric. Chord fill opacity (0-1). Default 0.8.

label_cex

Numeric. Sector label size multiplier. Default 0.8.

directional

Logical. Draw directional arrows. Default FALSE.

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 7.

Value

The contingency matrix (2 variables) or link data frame (3+ variables), or a named list of those when facet.by is used (invisibly).