Single Trajectory Analysis

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.