Pathway state hierarchy butterfly plot — PlotPathwayButterfly • scSidekick

Scores cells against four pathways, maps them to a 2-D hierarchy coordinate system, and produces a butterfly layout: one large overview panel (all cells colored by group.by) plus one small panel per group level (group highlighted in color; remaining cells in gray). When split.by is supplied, a separate figure is produced for each split level.

Usage

PlotPathwayButterfly(
  seurat_object,
  group.by,
  quadrant_order,
  split.by = NULL,
  gene_sets = NULL,
  pathway_sets = list(Hallmark = list(category = "H")),
  species = "Homo sapiens",
  quadrant_labels = NULL,
  group_colors = NULL,
  assay = "RNA",
  layer = "counts",
  subsample = FALSE,
  n_cells = 20000L,
  subsample_warn_at = 50000L,
  center = TRUE,
  log_scale = TRUE,
  overview_title = NULL,
  overview_size = 2,
  panel_ncol = NULL,
  point_size = 0.3,
  point_alpha = 0.6,
  label_size_large = 5,
  label_size_small = 2.5,
  title_size_large = 12,
  title_size_small = 8,
  width = NULL,
  height = NULL,
  file_name = NULL,
  timestamp = FALSE,
  output_dir = NULL,
  caffeinate = FALSE
)

Arguments

seurat_object: A Seurat object.
group.by: Character. Metadata column for cell grouping and coloring.
quadrant_order: Character vector of exactly four pathway names, in order: bottom-left, bottom-right, top-left, top-right. Names must match either names(gene_sets) (custom mode) or pathway names in the requested MSigDB collection.
split.by: Character or NULL. Metadata column whose levels each generate a separate butterfly figure. Default: NULL.
gene_sets: Named list of character vectors — one element per pathway. When NULL (default), gene sets are fetched from MSigDB via msigdbr using pathway_sets and filtered to quadrant_order.
pathway_sets: Named list specifying MSigDB collection(s) to search. Each element is a list with category and optional subcategory. Only used when gene_sets = NULL. Default: list(Hallmark = list(category = "H")).
species: Species string for msigdbr. Default: "Homo sapiens".
quadrant_labels: Character vector of four display labels for the corner boxes (order matches quadrant_order: bl, br, tl, tr). Defaults to auto-shortened pathway names.
group_colors: Named character vector mapping group levels to colors. Defaults to PrepObject colors or auto-generated palette.
assay: Assay to extract counts from. Default: "RNA".
layer: Layer / slot name. Default: "counts".
subsample: Logical. When TRUE, randomly sample n_cells cells before scoring. Default: FALSE.
n_cells: Integer. Number of cells to sample when subsample = TRUE. Default: 20000L.
subsample_warn_at: Integer or NULL. If the cell count exceeds this value and subsample = FALSE, a message is emitted. Set NULL to silence. Default: 50000L.
center: Logical. Column-center scores before hierarchy transform. Default: TRUE.
log_scale: Logical. Apply log2 scaling to hierarchy coordinates. Default: TRUE.
overview_title: Character. Title for the overview panel. Defaults to the object name stored by PrepObject.
overview_size: Numeric. Width of the overview panel relative to one small panel column. Default: 2.
panel_ncol: Integer or NULL. Number of columns in the small- panel grid. Defaults to ceiling(n_groups / 2).
point_size: Numeric. Point size. Default: 0.3.
point_alpha: Numeric. Point alpha. Default: 0.6.
label_size_large: Numeric. Corner label size for the overview panel. Default: 5.
label_size_small: Numeric. Corner label size for small panels. Default: 2.5.
title_size_large: Numeric. Panel title font size for the overview. Default: 12.
title_size_small: Numeric. Panel title font size for small panels. Default: 8.
width: Numeric or NULL. PDF width in inches. When NULL (default), width is auto-sized as (overview_size + panel_ncol) * 1.5.
height: Numeric or NULL. PDF height in inches. When NULL (default), height is auto-sized as panel_nrow * 2.8 + 0.4.
file_name: Character or NULL. Output file name (without directory). Defaults to "<object_name> pathway butterfly.pdf".
timestamp: Logical. When TRUE, append a _YYYYMMDD-HHMMSS stamp to the saved file name(s) so repeated runs are versioned instead of overwriting the previous PDF. Default FALSE.
output_dir: Character or NULL. Directory for saving the PDF. Falls back to the PrepObject output directory. When NULL, the plot is printed to the active device.
caffeinate: Logical. Keep the machine awake during computation. Default: FALSE.

Value

Invisibly, a named list (one element per split level) each containing hierarchy (the X/Y coordinate data frame) and scores (the raw pathway score matrix, cells × pathways).

Quadrant layout

quadrant_order specifies the four pathway names in the order bottom-left, bottom-right, top-left, top-right. The Y-axis separates top from bottom; the X-axis gives the left-right balance within whichever axis dominates for each cell.

Scoring

Pathway scores are computed as the mean expression across each pathway's genes per cell (adapted from the scrabble R package). Scores are column-centered when center = TRUE (default) so that the mean score of each pathway across all cells is zero before the hierarchy transform.