Plot gene/feature expression trends across pseudotime

Smoothed expression (or any numeric feature) vs. pseudotime, one facet panel per feature, colored by group.by by default (or by color.by, when that's set instead) to compare trends across replicates or conditions. Equivalent to a geom_smooth() + facet_wrap(~Gene) script run by hand, but feature extraction goes through the same assay/version-safe path as the rest of scSidekick (.nk_feature_matrix(), which is what every other feature-plotting function in the package uses): genes are pulled via the v5/BPCells/sketch-safe .get_layer_data(), and numeric meta.data columns (module scores, cNMF usages, QC metrics, other pseudotime columns, ...) are used directly - both are accepted interchangeably in features.

Usage

PlotFeatureTrend(
  seurat_object,
  pseudotime.by,
  features,
  assay = NULL,
  layer = "data",
  min_expr = NULL,
  donor.by = NULL,
  color.by = NULL,
  group.by = NULL,
  groups = NULL,
  split.by = NULL,
  row.by = NULL,
  method = "loess",
  se = FALSE,
  add_cor = FALSE,
  cor_method = c("spearman", "pearson"),
  show_points = FALSE,
  point_size = 0.4,
  point_alpha = 0.25,
  scales = "free_y",
  ncol = NULL,
  colors = NULL,
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  file_name = NULL,
  width = NULL,
  height = NULL,
  timestamp = FALSE
)

Arguments

seurat_object: A Seurat object, typically after RunSlingshot.
pseudotime.by: Character. Numeric meta.data column for the x-axis (e.g. "Slingshot_Pseudotime_1").
features: Character vector. Gene names and/or numeric meta.data columns. Each gets its own facet panel.
assay: Character or NULL. Assay to pull gene expression from. NULL (default) uses DefaultAssay(seurat_object).
layer: Character. Assay layer/slot. Default "data" (log-normalized counts).
min_expr: Numeric or NULL. Expression floor applied before smoothing: observations with expression \(\le\) min_expr are dropped so the trend reflects the expressing population rather than being pulled toward zero by dropout. min_expr = 0 removes exact zeros. NULL (default) keeps all cells.
donor.by: Character or NULL. When a donor/patient column is given, cells are collapsed to one point per donor (mean x and mean y) before fitting, so both the trend and points reflect independent patients rather than cells. This is the honest way to relate a donor-level variable (e.g. age, a clinical score) to a per-cell value, and avoids drawing thousands of overlapping cell points. show_points defaults to TRUE when this is set. NULL (default) keeps cell-level.
color.by: Character or NULL. Metadata column to color the smoothed trend lines by (e.g. "Sample", to see whether replicates agree). NULL (default) falls back to group.by for coloring, matching every other scSidekick plotting function's default; pass an explicit color.by to color by something other than the variable used to restrict cells.
group.by: Character or NULL. Metadata column that (1) colors the trend lines when color.by is NULL, and (2), paired with groups, restricts which cells are plotted (e.g. the trend within one cluster only) regardless of which variable ends up coloring the plot.
groups: Character vector or NULL. Which level(s) of group.by to keep. NULL (default, when group.by is set) keeps all levels.
split.by: Character or NULL. Creates column facets - one figure panel per level, each drawn from an independent subset of cells (tiled with patchwork). NULL (default) = no column split.
row.by: Character or NULL. Creates row facets, the same way as split.by. Combined with split.by produces a two-way grid. NULL (default) = no row split.
method: Character. Smoothing method passed to ggplot2::geom_smooth(). "loess" (default) fits a flexible, non-parametric curve - appropriate when the relationship's shape is unknown or non-monotonic. Use "lm" for a straight-line (linear) fit when the relationship looks linear/monotonic (e.g. after inspecting it with add_cor = TRUE, or from prior knowledge of the variables); "glm" is also accepted for a generalized linear fit.
se: Logical. Show the smoother's standard-error ribbon. Default FALSE.
add_cor: Logical. Annotate each facet with a correlation coefficient and p-value (via ggpubr::stat_cor()), computed directly from the plotted x/y (donor-level when donor.by is set) - this is the direct way to test the relationship shown by the trend line without routing through CorrelateGene()/PlotCorrelation(), which are built around a gene-vs-many-genes screen keyed on a Seurat object rather than an arbitrary x/y pair. When a color variable is in effect (color.by, or group.by as its fallback), one annotation is shown per color group. Default FALSE.
cor_method: Character. "spearman" (default; rank-based, appropriate for monotonic but not necessarily linear relationships) or "pearson" (linear correlation). Only used when add_cor = TRUE.
show_points: Logical. Overlay the raw observations under the trend. Besides showing individual points, this trains the y-axis on the full data range - geom_smooth() alone auto-scales the axis to the fitted line, which can look "clipped" relative to the spread of the data. Default FALSE.
point_size, point_alpha: Size and transparency of the overlaid points when show_points = TRUE. Defaults 0.4 and 0.25.
scales: Character. Passed to facet_wrap(). Default "free_y" (expression ranges differ across genes).
ncol: Integer or NULL. Facet columns. NULL auto-picks.
colors: Named color vector for the coloring variable (color.by or, when that's NULL, group.by). NULL auto-resolves from PrepObject or Nour_pal.
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.
width, height: Numeric or NULL. Saved PDF dimensions in inches. NULL (default) auto-sizes from the number of facets (or, with split.by/row.by, from the panel grid).
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

A ggplot object, or (with split.by/row.by) a patchwork object.