Violin / box / bar plots for gene expression and numeric metadata

Plots one panel per feature - either a gene expression value pulled from the specified assay layer or a numeric metadata column - grouped by a categorical metadata variable on the x-axis. Multiple features are assembled with patchwork.

Usage

PlotFeature(
  data,
  features,
  group.by,
  split.by = NULL,
  row.by = NULL,
  exclude = NULL,
  plot_type = c("violin", "box", "both", "bar"),
  add_points = FALSE,
  point_size = 0.3,
  alpha = 0.7,
  add_stats = FALSE,
  comparisons = NULL,
  ref_group = NULL,
  hide_ns = FALSE,
  stat_alpha = 0.05,
  label_format = c("stars", "p.format"),
  ncol = NULL,
  downsample = NULL,
  colors = NULL,
  assay = "RNA",
  layer = "data",
  output_dir = NULL,
  object_name = "",
  file_name = NULL,
  pdf_width = NULL,
  pdf_height = NULL,
  timestamp = FALSE
)

Arguments

data: A Seurat object or a plain data frame.
features: Character vector of gene names and/or numeric metadata column names. Mixed vectors are supported.
group.by: Character. Categorical metadata column for the x-axis (groups / conditions).
split.by: Character or NULL. Creates column facets within each feature panel - one panel per level of split.by.
row.by: Character or NULL. Creates row facets within each feature panel. Combined with split.by produces a two-way facet_grid.
exclude: Named list of values to exclude before plotting. Each name is a column name and each value is a character vector of levels to drop. Can target group.by, split.by, row.by, or any other metadata column. Example: list(Cognitive.Status = "Reference", Sex = "Unknown").
plot_type: One of "violin" (default), "box", "both" (violin with a thin white box overlay), or "bar" (mean ± SE bar chart).
add_points: Logical. Overlay jittered individual points. Default FALSE.
point_size: Numeric. Size of jittered points. Default 0.3.
alpha: Numeric. Fill transparency for violins / bars. Default 0.7.
add_stats: Logical. Add Wilcoxon significance brackets via ggsignif. Default FALSE. Caveat: these tests are computed per cell, so with many cells per group they are pseudoreplicated and p-values are inflated (brackets often read "***" regardless of the true effect). They are useful as a descriptive overlay only; for valid between-sample inference aggregate to samples with PlotPseudoBulk. A warning is emitted when add_stats = TRUE.
comparisons: List of length-2 character vectors specifying pairs to compare. NULL (default) tests all pairwise combinations, or all vs ref_group when that is set.
ref_group: Character or NULL. Reference group for comparisons (all others tested against it).
hide_ns: Logical. Suppress "ns" brackets. Default FALSE.
stat_alpha: Numeric. Significance threshold used for bracket labeling and for determining star levels (* at stat_alpha, ** at stat_alpha / 5, *** at stat_alpha / 50). Default 0.05.
label_format: One of "stars" (default: *, **, ***) or "p.format" (numeric p-value shown).
ncol: Integer or NULL. Columns in the patchwork assembly. NULL = min(n_features, 3).
downsample: Integer or NULL. If supplied, downsample to at most this many cells total (balanced across group.by levels) before plotting. NULL (default) uses all cells.
colors: Named character vector of fill colors for group.by levels. NULL auto-resolves from PrepObject (if a Seurat object is passed) or SelectColors().
assay: Character. Seurat assay to pull gene expression from. Default "RNA".
layer: Character. Assay layer / slot. Default "data" (log-normalized counts).
output_dir: Character or NULL. Save directory. Walks up from PrepObject when a Seurat object is passed.
object_name: Character. Filename prefix. Walks up from PrepObject when a Seurat object is passed.
file_name: Character or NULL. Base name (no extension) for the saved PDF. When supplied it is used verbatim (the object_name, feature, group.by/split.by and plot_type pieces are skipped). NULL (default) auto-builds the name from those variables.
pdf_width: Numeric or NULL. Override the auto-calculated PDF width in inches. NULL (default) sizes automatically from the number of groups, splits, and features.
pdf_height: Numeric or NULL. Override the auto-calculated PDF height in inches. NULL (default) sizes automatically from the number of row facets and features.
timestamp: Logical. When TRUE, append a _YYYYMMDD-HHMMSS stamp to the saved file name so repeated runs are versioned instead of overwriting the previous PDF. Default FALSE.

Value

When one feature is requested, a single ggplot2 object. When multiple features are requested, a patchwork combined plot. The plot is also saved as a PDF when output_dir is available.

Details

Feature type is auto-detected: gene names found in the assay are extracted as log-normalized expression; numeric metadata columns are used directly. Passing a categorical metadata column raises a helpful error pointing to the appropriate scSidekick visualization function instead.

Examples

if (FALSE) { # \dontrun{
# Gene expression violin plot
PlotFeature(SeuratObj, features = c("CD3E", "CD79A", "LYZ"),
  group.by = "CellType")

# Numeric metadata with split + stats, excluding a reference group
PlotFeature(SeuratObj, features = "Age.at.Death",
  group.by  = "Dementia.AD",
  split.by  = "Sex",
  exclude   = list(Cognitive.Status = "Reference"),
  add_stats = TRUE,
  plot_type = "box")

# Two-way facet: split.by columns × row.by rows
PlotFeature(SeuratObj, features = c("CD3E", "LYZ"),
  group.by = "Group",
  split.by = "Timepoint",
  row.by   = "Sex")
} # }