Skip to contents

Overlay a Slingshot trajectory on a DimPlot

PlotTrajectory.Rd

Draws a standard cluster DimPlot with the Slingshot trajectory overlaid, in one of two styles:

  • style = "straight" (default) - straight segments between cluster centroids, following the cluster-level minimum spanning tree Slingshot fit (slingshot::slingMST()). This is the clean, DDRTree-like look that stays legible with many clusters, and works on any plot reduction since only the MST's cluster connectivity is reused - the node positions come from this plot's own reduction.

  • style = "curves" - Slingshot's smoothed per-lineage principal curves (slingshot::slingCurves()). These live in whatever reduction Slingshot was fit on, so this style requires reduction to match seurat_object@misc$slingshot$reduction (e.g. fit and plot both on "umap"); otherwise the curve coordinates would not correspond to the plotted axes, and this function stops rather than draw a misleading overlay.

Usage

PlotTrajectory(
  seurat_object,
  reduction = "umap",
  group.by = NULL,
  split.by = NULL,
  row.by = NULL,
  lineages = NULL,
  style = c("straight", "curves"),
  colors = NULL,
  pt.size = 0.4,
  line.color = "black",
  line.width = 0.8,
  label_lineages = TRUE,
  arrow = TRUE,
  label = TRUE,
  number_labels = FALSE,
  legend.side = "bottom",
  legend_nrow = 2,
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  file_name = NULL,
  width = NULL,
  height = NULL,
  timestamp = FALSE
)

Arguments

seurat_object

A Seurat object previously processed by RunSlingshot.

reduction

Character. Reduction to plot on. Default "umap".

group.by

Character or NULL. Metadata column for point color. NULL (default) uses the cluster.by stored by RunSlingshot.

split.by

Character or NULL. Metadata column for columns in a multi-panel grid (e.g. one panel per sample/condition). NULL (default) walks up to the split.by stored by PrepObject; a single panel is drawn when neither this nor row.by is set. Each panel reuses the same fitted Slingshot model - only which cells are drawn differs - and the whole grid shares one legend, matching PlotDimPlots.

row.by

Character or NULL. Metadata column for rows in the grid, combined with split.by for a two-way facet. NULL (default; no row faceting).

lineages

Integer/character vector or NULL. Which lineages to draw (e.g. c(1, 2) or c("Lineage1", "Lineage2")). NULL (default) draws all.

style

"straight" or "curves". See Description.

colors

Named color vector. NULL auto-resolves from PrepObject or Nour_pal.

pt.size

Numeric. Point size. Default 0.4.

line.color

Character. Trajectory line color. Default "black".

line.width

Numeric. Trajectory line width. Default 0.8.

label_lineages

Logical. When more than one lineage is drawn, map line type (solid/dashed/dotted/...) to lineage and add a "Lineage" legend, so overlapping trajectory lines can be told apart. Color is left alone (still line.color) so this doesn't collide with the cluster color legend. Default TRUE; has no visible effect (and no legend) when only one lineage is drawn.

arrow

Logical. Draw arrowheads on straight segments (ignored for style = "curves", which is unordered per point). Default TRUE.

label

Logical. Label cluster centroids. Default TRUE.

number_labels

Logical. When TRUE, both the legend and (if label = TRUE) the centroid labels use a zero-padded index (e.g., legend "01. CellType", centroid "01") instead of the actual cluster name, matching PlotDimPlots's convention. Useful when there are many clusters or the names are too long to label directly on the plot. Default FALSE (legend and centroid labels show the real cluster name, unnumbered).

legend.side

Character. Legend position, matching PlotDimPlots: "bottom" (default), "top", "left", or "right".

legend_nrow

Integer. Rows for the cluster legend when legend.side is "bottom"/"top". Default 2, matching PlotDimPlots's default - keeping this the same makes the two functions' output comparable side by side.

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) uses a fixed 6 x 5.5 in panel (scaled up per grid panel when split.by/row.by is set).

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 (or, when split.by/row.by is set, a patchwork) object, invisibly if saved.