playbooks

home / skills / starlitnightly / omicverse / single-trajectory

single-trajectory skill

/.claude/skills/single-trajectory

This skill helps you reproduce and extend single-trajectory analyses by integrating PAGA, Palantir, VIA, velocity coupling, and fate scoring notebooks.

npx playbooks add skill starlitnightly/omicverse --skill single-trajectory

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
4.3 KB
---
name: single-trajectory-analysis
title: Single-trajectory analysis
description: Guide to reproducing OmicVerse trajectory workflows spanning PAGA, Palantir, VIA, velocity coupling, and fate scoring notebooks.
---

# Single-trajectory analysis skill

## Overview
This skill describes how to reproduce and extend the single-trajectory analysis workflow in `omicverse`, combining graph-based trajectory inference, RNA velocity coupling, and downstream fate scoring notebooks.

## Trajectory setup
- **PAGA (Partition-based graph abstraction)**
  - Build a neighborhood graph (`pp.neighbors`) on the preprocessed AnnData object.
  - Use `tl.paga` to compute cluster connectivity and `tl.draw_graph` or `tl.umap` with `init_pos='paga'` for embedding.
  - Interpret edge weights to prioritize branch resolution and seed paths.
- **Palantir**
  - Run `Palantir` on diffusion components, seeding with manually selected start cells (e.g., naïve T cells).
  - Extract pseudotime, branch probabilities, and differentiation potential for subsequent overlays.
- **VIA**
  - Execute `via.VIA` on the kNN graph to identify lineage progression with automatic root selection or user-defined roots.
  - Export terminal states and pseudotime for cross-validation against PAGA and Palantir results.

## Velocity coupling (VIA + scVelo)
- Use `scv.pp.filter_and_normalize`, `scv.pp.moments`, and `scv.tl.velocity` to generate velocity layers.
- Provide VIA with `adata.layers['velocity']` to refine lineage directionality (`via.VIA(..., velocity_weight=...)`).
- Compare VIA pseudotime with scVelo latent time (`scv.tl.latent_time`) to validate directionality and root selection.

## Downstream fate scoring notebooks
- **`t_cellfate*.ipynb`**: Map lineage probabilities onto T-cell subsets, quantify fate bias, and visualize heatmaps.
- **`t_metacells.ipynb`**: Aggregate metacell trajectories for robustness checks and meta-state differential expression.
- **`t_cytotrace.ipynb`**: Integrate CytoTRACE differentiation potential with velocity-informed lineages for maturation scoring.

## Required preprocessing
1. Quality control: remove low-quality cells/genes, apply doublet filtering.
2. Normalization & log transformation (`sc.pp.normalize_total`, `sc.pp.log1p`).
3. Highly variable gene selection tailored to immune datasets (`sc.pp.highly_variable_genes`).
4. Batch correction if necessary (e.g., `scvi-tools`, `bbknn`).
5. Compute PCA, neighbor graph, and embedding (UMAP/FA) used by all trajectory methods.
6. For velocity: compute moments on the same neighbor graph before running VIA coupling.

## Parameter tuning
- Neighbor graph `n_neighbors` and `n_pcs` should be harmonized across PAGA, VIA, and Palantir to maintain consistency.
- In VIA, adjust `knn`, `too_big_factor`, and `root_user` for datasets with uneven sampling.
- Palantir requires careful start cell selection; use marker genes and velocity arrows to confirm.
- For PAGA, tweak `threshold` to control edge sparsity; ensure connected components reflect biological branches.
- Velocity estimation: compare `mode='stochastic'` vs `mode='dynamical'` in scVelo; recalibrate if terminal states disagree with VIA.

## Visualization and export
1. Overlay PAGA edges on UMAP (`scv.pl.paga`) and annotate branch labels.
2. Plot Palantir pseudotime and branch probabilities on embeddings.
3. Visualize VIA trajectories using `via.plot_fates` and `via.plot_scatter`.
4. Export pseudotime tables and fate probabilities to CSV for downstream notebooks.
5. Save high-resolution figures (PNG/SVG) and notebook artifacts for reproducibility.
6. Update notebooks with consistent color schemes and metadata columns before sharing.

## Troubleshooting tips
- **Missing velocity layers**: re-run `scv.pp.moments` and `scv.tl.velocity` ensuring `adata.layers['spliced']`/`['unspliced']` exist; verify loom/H5AD import preserved layers.
- **Disconnected PAGA graph**: inspect neighbor graph or adjust `n_neighbors`; confirm batch correction didn’t fragment the manifold.
- **Palantir convergence issues**: reduce diffusion components or reinitialize start cells; ensure no NaN values in data matrix.
- **VIA terminal states unstable**: increase iterations (`cluster_graph_pruning_iter`), or provide manual terminal state hints based on marker expression.
- **Notebook kernel memory errors**: downsample cells or precompute summaries (metacells) before rerunning.

Overview

This skill guides reproducible single-trajectory analysis workflows that combine PAGA, Palantir, VIA, RNA velocity coupling, and downstream fate scoring notebooks. It explains preprocessing, parameter harmonization, velocity integration, and exportable outputs so you can reproduce and extend trajectory results across immune and multi-omics datasets. The focus is on practical steps, cross-validation strategies, and troubleshooting common failures.

How this skill works

The workflow builds a common neighbor graph and embedding, then runs complementary trajectory methods: PAGA for global branch structure, Palantir for probabilistic pseudotime and branch probabilities, and VIA for automatic lineage detection with optional velocity coupling. scVelo produces velocity layers and latent time that VIA can consume to refine directionality. Outputs (pseudotime, branch/fate probabilities, terminal states) are exported for fate scoring and visualization notebooks.

When to use it

  • Comparing multiple trajectory inference approaches to confirm lineage structure.
  • Mapping fate probabilities and differentiation potential in immune single-cell datasets.
  • Integrating RNA velocity to resolve directionality in ambiguous branches.
  • Generating robust metacell summaries or fate heatmaps for downstream analysis.
  • Validating terminal states across PAGA, Palantir, and VIA before biological interpretation.

Best practices

  • Harmonize n_neighbors and n_pcs across PAGA, VIA, and Palantir to keep manifolds comparable.
  • Run scVelo moments on the same neighbor graph used by VIA before coupling velocity layers.
  • Use marker genes and velocity arrows to choose Palantir start cells and to validate VIA roots.
  • Export pseudotime and fate probabilities to CSV and save high-resolution figures for reproducibility.
  • Downsample or compute metacells when memory or kernel limits impede full-scale runs.

Example use cases

  • Quantifying T-cell fate bias: map lineage probabilities onto T-cell subsets and produce fate heatmaps.
  • Cross-validating terminal states: compare VIA terminal states with PAGA connectivity and Palantir branch probabilities.
  • Velocity-informed maturation scoring: combine scVelo latent time with CytoTRACE and VIA lineages.
  • Robust trajectory summaries: aggregate metacell trajectories for differential expression across meta-states.
  • Troubleshooting dataset artifacts: identify when batch correction or neighbor settings fragment biological branches.

FAQ

What preprocessing is required before trajectory analysis?

Perform QC (filter low-quality cells/genes, doublet removal), normalization and log1p, select highly variable genes, correct batches if needed, compute PCA and a neighbor graph, then derive UMAP/FA embeddings.

How do I validate directionality between methods?

Compare VIA pseudotime and roots with scVelo latent time and velocity vectors; use marker genes and Palantir start cells as orthogonal checks.

What to do if PAGA is disconnected?

Inspect and adjust neighbor graph parameters (n_neighbors, n_pcs), check batch correction effects, or relax PAGA threshold to reconnect biologically related components.