Fit Slingshot pseudotime directly on a Seurat reduction

Runs slingshot directly on a Seurat dimensional reduction (PCA, Harmony, or any other integrated embedding) and a cluster identity column - no SingleCellExperiment conversion involved. Slingshot's own algorithm only ever needs a reduced-dimension matrix and cluster labels (it builds a cluster-level minimum spanning tree, then fits a principal curve per lineage), so bypassing the object conversion avoids the two biggest practical problems with Seurat-wrapper packages for trajectory inference:

the expression matrix is never touched, so there is no renormalize-already-normalized-data risk downstream, and
there is no assay/version stripping to do first - it does not matter whether the object has BPCells, sketch, or multiple v5 assays, since only the embedding matrix (always dense) and a metadata column are read.

Results are written back onto seurat_object so they can be reused without recomputation: per-cell pseudotime as meta.data columns (<prefix>_Pseudotime_1, _2, ...) and the fitted model, cluster MST, and lineage paths in seurat_object@misc$slingshot. Use SlingshotLineages afterward to see which lineage number corresponds to which cluster path.

Usage

RunSlingshot(
  seurat_object,
  cluster.by,
  reduction = NULL,
  dims = NULL,
  max_dims = 20L,
  start.clus = NULL,
  end.clus = NULL,
  approx_points = NULL,
  use_sketch = TRUE,
  downsample = NULL,
  prefix = "Slingshot",
  progress = TRUE,
  poll_interval = 10,
  caffeinate = FALSE,
  output_dir = NULL
)

Arguments

seurat_object: A Seurat object with at least one dimensional reduction computed.
cluster.by: Character. Metadata column of cluster/cell-type identities to build the lineage structure on.
reduction: Character or NULL. Reduction to fit on. NULL (default) auto-detects: prefers "harmony" or any other integration-style reduction (name matching "integrated", "scvi", "mnn", "scanorama") over a plain "pca", so batch-corrected embeddings are used by default when present.
dims: Integer vector or NULL. Which components of reduction to use. NULL (default) uses the first max_dims available - see max_dims.
max_dims: Integer. When dims is NULL, the number of leading components to use from reduction. Default 20L. Principal-curve fitting cost scales with dimensionality (roughly 6x slower going from 2 to 50 dims at matched cell count in local testing), so a Harmony/PCA reduction with 30-50 computed components is capped rather than used in full. Ignored if dims is supplied explicitly, or if reduction has fewer than max_dims components (e.g. a 2D UMAP).
start.clus: Character or NULL. Root cluster (level of cluster.by) that lineages should originate from. Strongly recommended - without it, Slingshot's MST is unrooted and lineage direction is arbitrary.
end.clus: Character vector or NULL. Optional terminal cluster(s) to constrain lineage endpoints.
approx_points: Integer or NULL. Passed to slingshot::slingshot(); reduces the number of points used to fit principal curves, which speeds up large runs at a small cost to smoothness. NULL uses Slingshot's default (no approximation).
use_sketch: Logical. If the object has a "sketch" assay (from SketchData()), fit on those cells only, as a fast preview. Default TRUE. Has no effect if no "sketch" assay exists.
downsample: Integer or NULL. If supplied (and no usable "sketch" assay was found), cap each cluster.by level at this many cells before fitting, for a fast preview on large objects. Cells not included in the fit get NA pseudotime. Default NULL (use all cells).
prefix: Character. Prefix for the pseudotime meta.data columns. Default "Slingshot".
progress: Logical. Show live "still fitting" heartbeat messages while Slingshot runs, so a long fit is never silent. Requires the callr package (runs the fit in a background process so R can poll and print while waiting); this also keeps the wait itself interruptible via Ctrl+C at any point, unlike being blocked directly inside Slingshot's own fitting code. Falls back to a plain blocking call with an upfront message only if callr is not installed. Default TRUE.
poll_interval: Numeric. Seconds between heartbeat messages when progress = TRUE. Default 10.
caffeinate: Logical. Prevent the machine from sleeping for the duration of the fit (macOS/Windows only; see RunCellChat). Default FALSE.
output_dir: Character or NULL. Directory to write analysis_params.json documenting this run. NULL (default) walks up to the output_dir stored by PrepObject (respecting AutoSavePlots); pass NA to suppress entirely.

Value

seurat_object with pseudotime columns added to meta.data and the fitted result in @misc$slingshot.