Slingshot Analysis
Infer cluster-supported trajectories and deliver an editable, coordinated figure set. Use the bundled R helpers for fitting and plotting; adapt scientific choices to the dataset. For a plotting-only request, reuse the saved fit and cell universe.
Plot preview
Click the figure to view it at full size. This preview uses real mouse single-cell data from GSE72857, following the NBIS tutorial. The run used 2,074 cells and found five lineages with automatic start/end selection. The trajectory overview shows all lineages; the individual examples focus on Lineage1. Cluster labels are used because cell-type annotations are unavailable. Genes are ranked by expression change; module heatmaps group selected genes by their smoothed expression patterns.
Individual plots and functions
Store each figure directly in assets/ under its descriptive name. The overview is a combined preview; individual figures have no panel letters or numbering.
| Figure | Plotting function / returned plot | Example |
|---|---|---|
| Trajectory overview | plot_slingshot() → plots$overview |
Image |
| Lineage pseudotime | plot_slingshot() → plots$pseudotime |
Image |
| Cluster pseudotime violin | plot_slingshot() → plots$pseudotime_violin |
Image |
| Lineage gene trends | plot_slingshot_genes() → plots$gene_trends_01 |
Image |
| Lineage module heatmap | draw_slingshot_module_heatmap() — one lineage |
Image |
| Group pseudotime violin | plot_slingshot() → plots$group_pseudotime_violin |
Image |
| Group gene trends | plot_slingshot_group_genes() → plots$group_gene_trends_01 |
Image |
| Lineage comparison heatmap | draw_slingshot_module_heatmap() — two lineages |
Image |
These example figures are PNG only; the plotting functions emit both PNG and PDF into the output directory, so publication-quality vector versions are always regenerated rather than shipped.
The overview and violin/gene functions are in slingshot_plots.R.txt; module heatmap functions are in slingshot_module_heatmap.R.txt.
Use the plotting guide to build these views for the user's data. Gene plots require normalized expression; cell-type violins use the cell-type metadata column (or labeled clusters when annotations are unavailable).
Optional group comparison
Supply group_col to add descriptive group pseudotime violins, and use plot_slingshot_group_genes() for separate group curves on the same lineage time axis. Group comparisons appear in the overview when groups are supplied. The previews use explicitly artificial Group A/B labels, randomly balanced within clusters, solely to demonstrate the layout. Generate no synthetic labels for user analyses unless requested. Formal donor-aware group-difference testing is not implemented by these plotting helpers.
Module heatmap previews
Use the single-lineage layout for one trajectory. Use the mirrored two-lineage layout for a selected pair; it shares gene rows and an expression scale across both trajectories. The continuous fitted heatmap is complete; support diagnostics are exported beside it rather than shown as blank heatmap bands.
Workflow
- Establish the biological process, relevant cell population, cluster column, sample/donor column, existing reductions, and any user-specified starting or ending clusters. Use supplied starts and ends; leave each unspecified setting as
NULLso Slingshot decides. Do not ask the user to choose a root or endpoints just to run the analysis. Clarify only when a supplied label cannot be mapped unambiguously to observed clusters. - Read analysis.md for input adapters, fitting, output contracts, and optional tradeSeq modeling. Inspect the object before choosing an assay or layer. The helpers use cell-ID-aligned matrices so Seurat, SingleCellExperiment, and exported data share one workflow.
- Fit with slingshot_analysis.R.txt. Prefer an appropriate PCA/diffusion/latent space for inference; preserve existing UMAP for display. Pass supplied starting clusters through
rootand supplied endpoints throughend_clusters; both default toNULL. Record user-provided biological rationale when available, without requiring it to apply the user's choices. Report the fitted roots/endpoints and whether they were selected automatically or constrained by the user. - Check cluster/sample representation, disconnected populations, plausible paths, and sensitivity to reasonable cluster resolutions and dimensions. Compare matched lineage paths and within-lineage ranks, since lineage numbers and raw scales can change between fits. Do not force unrelated populations into one tree.
- Read plotting.md, then use slingshot_plots.R.txt. Produce overview, separate lineage pseudotime panels, and curve-weight panels. Add pseudotime violins grouped by cell type and faceted by lineage. When normalized expression is available, produce a separate top-six gene-trend figure and module heatmap for each lineage. With exactly two lineages, also produce their comparison heatmap; with more lineages, compare user-selected pairs rather than choosing an arbitrary pair. Rank by supplied lineage-association adjusted P-values when available, otherwise by expression change; export the ranking method and selected genes. Omit unsupported panels and explain missing inputs.
- Export the fit, cell-by-lineage tables, parameters, colors, editable plot objects, PDF and 300-dpi PNG figures, and session information. Open the exported PNGs and check labels, legends, curve placement, and missing-data treatment before delivery. Write a brief interpretation with start/end selection, any supplied rationale, lineage paths, robustness findings, and limitations.
Keep figures focused on plot titles, axes, and legends. Do not add demo/simulation disclaimers to plot captions; preserve input provenance in accompanying notes.
Keep the trajectory, lineage pseudotime, cluster violins, gene trends, and module heatmap in the overview. When groups are supplied, place group violins beside cluster violins and group curves beside overall gene trends. Use descriptive titles without panel letters. Give the heatmap a dedicated column and omit the top-right count annotation. Violin plots use a raincloud layout: a soft half-violin, compact white boxplot, light observed-cell points, and cell counts. Density and boxplot statistics use every included cell; only displayed points are deterministically thinned to at most 40 per category per lineage. Reuse saved fits when adjusting layout. Top-gene plots use continuous fitted curves; their observed bin summaries and local support remain available in the exported tables.
Scientific and plotting invariants
- Pseudotime is relative ordering, not elapsed time or proof of ancestry. Slingshot curve weights are lineage membership weights, not calibrated fate probabilities.
- Automatically selected orientation is exploratory. Do not invent biological evidence for it or override Slingshot's choice based on UMAP position or cluster numbering. Specified endpoints constrain terminal nodes and may change topology; they do not exclude all other endpoints.
- Preserve one pseudotime and weight per cell per lineage. Shared progenitors can have positive weights in several lineages. Keep nonmembers' pseudotime as
NA; never replace it with zero or average mutually exclusive branches into a global progression score. - Extract analysis tables from the original fit. Use
embedCurves()only to visualize that fit in another space. Draw curve points inordorder, never by x coordinate. Do not overlay PCA coordinates on UMAP or infer new topology to make a plot look smoother. - Reuse cell coordinates, axis limits, named categorical colors, and lineage labels across comparable panels. Gray marks unassigned cells. Label any within-lineage 0–1 display rescaling; retain raw values for analysis. Rescaling does not align developmental stages between branches.
- Gene plots use explicitly selected normalized expression. Raw counts and original curve weights are required for count-based tradeSeq inference. Display smoothing and heatmap patterns are descriptive; they are not significance tests.
- Preserve biological replication in condition comparisons. Cell-level violin plots and batch covariates alone do not establish donor-level effects.
The module heatmap implementation is in slingshot_module_heatmap.R.txt, loaded by the main plotting script. Read the output layout when delivering the figures and tables.
Deliverables and entry points
| Request | Resource | Result |
|---|---|---|
| Fit from Seurat/SCE/matrices | Analysis guide | Saved fit, lineage paths, pseudotime and weights |
| Restyle or build figures | Plotting guide | Consistent, editable PDF/PNG panels |
| Test lineage-dependent genes | tradeSeq section | Model diagnostics and adjusted test results |
Core fitting requires slingshot; plotting requires ggplot2 >= 3.4.0 and patchwork, with ComplexHeatmap and circlize for module heatmaps. SeuratObject, SingleCellExperiment, and tradeSeq are conditional dependencies. Check the current environment and use a compatible Bioconductor release when dependencies need installation; scripts do not silently install packages.
> Packaging note. Scripts and tables in this skill carry a .txt suffix on their
> original extension (e.g. .R.txt, .tsv.txt) because the SkillHub upload allowlist
> does not accept .R or .tsv. This is cosmetic: Rscript is extension-agnostic, so
> Rscript scripts/<name>.R.txt ... behaves exactly like .R, and tab-separated data
> parses identically from .tsv.txt. Keep the suffix when repackaging.
> Images. Example figures ship as .svg — a text-format container with the
> original raster embedded as base64 — because the SkillHub upload blacklist rejects
> .png, .jpg, .gif, .webp and other binary image extensions. Rendering is
> unchanged; open the .svg in any browser or editor to view the figure. Keep this
> format when repackaging, and keep the original PNGs out of the uploaded package.
