Skip to contents

Pseudobulk box + dot plots for gene expression

PlotPseudoBulk.Rd

Plots mean gene expression per donor (or per donor x cell type, etc.) as box plots with individual donor dots overlaid - the standard pseudobulk visualization that avoids pseudo-replication.

Usage

PlotPseudoBulk(
  seurat_object,
  features,
  group.by,
  donor.by,
  split.by = NULL,
  row.by = NULL,
  exclude = NULL,
  min_cells = 0L,
  show_n = TRUE,
  add_stats = FALSE,
  test = c("wilcox.test", "t.test"),
  comparisons = NULL,
  ref_group = NULL,
  hide_ns = FALSE,
  stat_alpha = 0.05,
  label_format = c("stars", "p.format"),
  point_size = 1.5,
  jitter_width = 0.15,
  box_width = 0.5,
  alpha = 0.7,
  ncol = NULL,
  colors = NULL,
  assay = "RNA",
  layer = "data",
  output_dir = NULL,
  object_name = "",
  pdf_width = NULL,
  pdf_height = NULL
)

Arguments

seurat_object

A Seurat object.

features

Character vector. Gene names and/or numeric meta.data columns (e.g. a module score, QC metric, or pseudotime). Numeric metadata columns are aggregated to donor level (per-group mean) exactly like gene expression, so they get the same boxplots and statistics - unlike PlotMetaSummary, which shows numeric metadata without stats.

group.by

Character. Categorical metadata column shown on the x-axis (e.g. "Cognitive.Status" or "Condition").

donor.by

Character. Metadata column that identifies one biological replicate (e.g. "Donor.ID"). One dot per unique value.

split.by

Character or NULL. Column facets within each panel (e.g. "CellType").

row.by

Character or NULL. Row facets within each panel. Combined with split.by gives a two-way grid.

exclude

Named list of values to drop before plotting. Each name is a column and each value is a character vector of levels to remove. Example: list(Cognitive.Status = "Reference").

min_cells

Integer. Drop pseudobulk groups (donor x group combinations) with fewer than this many cells. Default 0L.

show_n

Logical. Annotate each x-axis group with the number of donors (or pseudobulk samples) in that group after all filtering. Shown as n=X below the x-axis ticks. Default TRUE.

add_stats

Logical. Add significance brackets via ggsignif. Default FALSE.

test

Character. Test used for the brackets: "wilcox.test" (default) or "t.test". Note that at small donor counts the rank-based Wilcoxon test is discrete and cannot reach p < 0.05 (e.g. 3 vs 3 has a minimum two-sided p of ~0.1, so brackets are always ns); "t.test" is usually the better choice for donor-level pseudobulk with few, roughly continuous replicates.

comparisons

List of length-2 character vectors specifying pairs. NULL (default) tests all pairs, or all vs ref_group.

ref_group

Character or NULL. Reference group for comparisons.

hide_ns

Logical. Suppress "ns" brackets. Default FALSE.

label_format

One of "stars" (default) or "p.format".

point_size

Numeric. Size of donor dots. Default 1.5.

jitter_width

Numeric. Jitter width for donor dots. Default 0.15.

box_width

Numeric. Width of the box geom. Default 0.5.

alpha

Numeric. Fill transparency of boxes. Default 0.7.

ncol

Integer or NULL. Columns in the patchwork assembly. NULL = min(n_features, 3).

colors

Named character vector of fill colors for group.by levels. NULL auto-resolves from PrepObject or SelectColors().

assay

Character. Seurat assay. Default "RNA".

layer

Character. Assay layer. Default "data".

output_dir

Character or NULL. Save directory. Walks up from PrepObject.

object_name

Character. Filename prefix. Walks up from PrepObject.

pdf_width

Numeric or NULL. Override auto-calculated PDF width.

pdf_height

Numeric or NULL. Override auto-calculated PDF height.

Value

A ggplot2 object (single feature) or a patchwork combined plot (multiple features). Saved as PDF when output_dir is available.

Details

Each dot represents one unique donor.by value (e.g. one patient). Boxes show median, IQR, and 1.5x IQR whiskers. Dots are black.

On first call, pseudobulk means are computed on the fly and a hint is printed suggesting ComputePseudobulk for BPCells / large datasets. Pre-warm the cache with ComputePseudobulk() to make subsequent plots instant.

Examples

if (FALSE) { # \dontrun{
# Pre-warm cache (recommended for BPCells / large datasets)
SeuratObj <- ComputePseudobulk(SeuratObj,
  group.by = c("Donor.ID", "Cognitive.Status"))

# Per-donor boxplot, exclude reference group, add stats
PlotPseudoBulk(SeuratObj,
  features  = c("STAT3", "APOE"),
  group.by  = "Cognitive.Status",
  donor.by  = "Donor.ID",
  exclude   = list(Cognitive.Status = "Reference"),
  add_stats = TRUE)

# Per-donor x per-cell-type (split into column facets)
SeuratObj <- ComputePseudobulk(SeuratObj,
  group.by = c("Donor.ID", "Cognitive.Status", "CellType"))

PlotPseudoBulk(SeuratObj,
  features   = "APOE",
  group.by   = "Cognitive.Status",
  donor.by   = "Donor.ID",
  split.by   = "CellType",
  min_cells  = 10,
  add_stats  = TRUE,
  ref_group  = "Control")
} # }