Density or ridge plot for any gene or numeric metadata feature

A more general version of Seurat's RidgePlot() - one density (or ridge) per group.by level, for any single feature - but with the two things RidgePlot() does not support: a split.by fill within each ridge, and a facet.by panel split. That combination answers questions like "one ridge per Sample, one panel per Response" to check whether replicate samples show the same distribution shape within each condition.

feature is resolved the same assay/version-safe way as every other feature-plotting function in the package (.nk_feature_matrix()): gene names go through .get_layer_data() (v5/BPCells/sketch-safe), numeric meta.data columns (a pseudotime, a module score, a QC metric, ...) are used directly.

Usage

PlotFeatureDistribution(
  seurat_object,
  feature,
  group.by,
  split.by = NULL,
  facet.by = NULL,
  style = c("ridge", "density"),
  assay = NULL,
  layer = "data",
  min_expr = NULL,
  colors = NULL,
  scales = "fixed",
  ncol = NULL,
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  file_name = NULL,
  width = NULL,
  height = NULL
)

Arguments

seurat_object: A Seurat object.
feature: Character vector. One or more gene names and/or numeric meta.data columns. When several are supplied, one PDF is written per feature (the file name always includes the feature).
group.by: Character. Categorical meta.data column - one density/ridge per level.
split.by: Character or NULL. Categorical meta.data column used as a secondary fill within each group.by ridge. Only used when style = "ridge".
facet.by: Character or NULL. Categorical meta.data column to split the whole plot into panels via facet_wrap() (e.g. group.by = "Sample", facet.by = "Response" to check whether replicates overlap within each response group).
style: "ridge" (default, via ggridges) or "density" (overlaid geom_density() curves, fill = group.by; split.by is ignored for this style).
assay: Character or NULL. Assay to pull gene expression from. NULL (default) uses DefaultAssay(seurat_object).
layer: Character. Assay layer/slot. Default "data".
min_expr: Numeric or NULL. Expression floor: cells with expression \(\le\) min_expr are excluded so the distribution reflects the expressing population rather than a spike at zero from dropout. min_expr = 0 removes exact zeros. NULL (default) keeps all cells.
colors: Named color vector for the fill variable (split.by if set, else group.by). NULL auto-resolves from PrepObject or Nour_pal.
scales: Character. Passed to facet_wrap() when facet.by is set. Default "fixed" (keeps axes directly comparable across panels - usually what you want when checking whether distributions overlap).
ncol: Integer or NULL. Facet columns. NULL auto-picks.
output_dir: Character or NULL. Directory to save a PDF. NULL (default) walks up to the output_dir stored by PrepObject (respecting AutoSavePlots); pass NA to suppress entirely.
object_name, subset_name: Character. Output file-name prefixes.
file_name: Character or NULL. Base name (no extension) for the saved PDF. NULL auto-deduces a name that includes the feature, group.by and split.by. When file_name is given and several features are requested, the feature is appended so each still gets its own file.
width, height: Numeric or NULL. Saved PDF dimensions in inches. NULL (default) auto-sizes.

Value

A ggplot object for a single feature, or (for several features) a named list of ggplot objects, returned invisibly when saved to disk.