🏎️ Spatial Velocity

You are Spatial Velocity, the OmicsClaw skill for RNA velocity, directional state change, and kinetic / variational temporal ordering in spatial transcriptomics.

This skill follows the newer OmicsClaw unified template:

• method-specific core parameters stay explicit
• Python figures are the canonical standard gallery
• figure_data/ is the stable bridge for downstream styling
• optional R plotting is a separate visualization layer, not a second analysis engine

Why This Exists

• RNA velocity is highly sensitive to preprocessing, graph construction, and backend choice; hiding those settings behind one generic --method is not acceptable.
• Spatial users need both embedding-centric and tissue-centric views.
• OmicsClaw needs a stable output contract so future velocity backends can be added without breaking downstream interpretation or custom visualization.

Core Capabilities

1. scVelo kinetic backends
   • stochastic
   • deterministic
   • dynamical
2. Variational posterior backend
   • velovi
3. Standard OmicsClaw gallery
   • velocity stream on UMAP / spatial
   • phase portraits
   • spliced / unspliced proportion diagnostics
   • heatmap and PAGA summary panels
   • feature maps for speed, confidence, pseudotime, and latent time when available
4. Figure-ready exports
   • figures/manifest.json
   • figure_data/*.csv
   • figure_data/manifest.json
5. Stable tabular outputs
   • cell-level metrics
   • gene-level kinetic summaries
   • cluster-level velocity summaries
   • top-cell and top-gene exports

Input Convention

Input slot	Used by	Notes
adata.layers["spliced"]	all methods	required
adata.layers["unspliced"]	all methods	required
adata.obsm["spatial"]	spatial gallery panels	strongly recommended
adata.obsm["X_umap"]	embedding gallery panels	optional, but OmicsClaw will best-effort compute UMAP when absent
adata.obs[cluster_key]	grouped summaries, PAGA, proportions	defaults to leiden; OmicsClaw can auto-compute it

After the shared preprocessing stage, OmicsClaw also expects or creates:

adata.layers["Ms"]   # moment-smoothed spliced counts
adata.layers["Mu"]   # moment-smoothed unspliced counts

Method Contract

All methods share the same first stage:

1. filter / normalize
2. log1p
3. HVG selection when requested
4. PCA
5. neighbors
6. moments

That means the following are part of the scientific contract, not mere wrapper details:

• velocity_min_shared_counts
• velocity_n_top_genes
• velocity_n_pcs
• velocity_n_neighbors
• velocity_use_highly_variable
• velocity_graph_*

Workflow

1. Load the h5ad and verify spliced / unspliced layers exist.
2. Resolve cluster_key for grouped exports and gallery summaries.
3. Run shared preprocessing for the requested velocity contract.
4. Run the selected backend with method-specific core parameters only.
5. Persist velocity results into stable AnnData slots such as:
   • obs["velocity_speed"]
   • obs["velocity_confidence"]
   • obs["velocity_pseudotime"]
   • obs["latent_time"] when available
   • obs["root_cells"] / obs["end_points"] when available
6. Build gallery context from stable obs, obsm, and exported summary tables instead of from transient local variables.
7. Render the standard Python gallery through PlotSpec / VisualizationRecipe.
8. Export figure_data/ for downstream styling without recomputing the science.

Visualization Contract

OmicsClaw treats spatial-velocity visualization as a two-layer system:

1. Python standard gallery

   • the canonical analysis output
   • generated during the main run
   • built primarily from shared _lib/viz velocity primitives:
     • stream
     • phase
     • proportions
     • heatmap
     • paga
   • plus a small number of skill-specific summary plots

2. Optional R visualization layer

   • reads figure_data/
   • focuses on styling, layout, manuscript composition, and publication polish
   • must not rerun scVelo or VELOVI internally

This means:

• Python figures are the default OmicsClaw narrative users should interpret first.
• figure_data/*.csv is the stable handoff for downstream beautification.
• reproducibility/r_visualization.sh is an entrypoint for that optional layer.

CLI Reference

# Default stochastic scVelo run
oc run spatial-velocity \
  --input <processed.h5ad> --output <dir>

# Deterministic comparison run
oc run spatial-velocity \
  --input <processed.h5ad> \
  --method deterministic \
  --velocity-min-r2 0.02 \
  --velocity-min-likelihood 0.005 \
  --output <dir>

# Lightweight dynamical smoke test
oc run spatial-velocity \
  --input <processed.h5ad> \
  --method dynamical \
  --dynamical-n-top-genes 500 \
  --dynamical-max-iter 5 \
  --dynamical-n-jobs 4 \
  --output <dir>

# VELOVI
oc run spatial-velocity \
  --input <processed.h5ad> \
  --method velovi \
  --velovi-max-epochs 200 \
  --velovi-n-samples 25 \
  --output <dir>

# Demo
oc run spatial-velocity --demo --output /tmp/velocity_demo

Output Structure

<output_dir>/
├── report.md
├── result.json
├── processed.h5ad
├── figures/
│   ├── manifest.json
│   ├── velocity_stream_umap.png
│   ├── velocity_stream_spatial.png
│   ├── velocity_phase.png
│   ├── velocity_layer_proportions.png
│   ├── velocity_heatmap.png
│   ├── velocity_paga.png
│   └── ...
├── figure_data/
│   ├── manifest.json
│   ├── velocity_summary.csv
│   ├── velocity_cell_metrics.csv
│   ├── velocity_gene_summary.csv
│   ├── velocity_gene_hits.csv
│   ├── velocity_cluster_summary.csv
│   ├── velocity_top_cells.csv
│   ├── velocity_top_genes.csv
│   ├── velocity_run_summary.csv
│   ├── velocity_spatial_points.csv
│   └── velocity_umap_points.csv
├── tables/
│   ├── cell_velocity_metrics.csv
│   ├── gene_velocity_summary.csv
│   ├── velocity_gene_hits.csv
│   ├── velocity_cluster_summary.csv
│   ├── top_velocity_cells.csv
│   └── top_velocity_genes.csv
└── reproducibility/
    ├── commands.sh
    ├── requirements.txt
    ├── environment.txt
    └── r_visualization.sh

Method Notes

stochastic

• Best default first pass.
• Still graph-sensitive and not a full kinetic model.

deterministic

• Simpler steady-state baseline.
• Useful as a comparison against stochastic or dynamical when the user wants to separate graph sensitivity from heavier model complexity.

dynamical

• Adds kinetic fitting and latent-time support.
• Runtime and convergence cost are materially higher.
• latent_time is a fitted ordering, not clock time.

velovi

• Uses a variational posterior model after the shared moment construction step.
• Training settings are scientifically relevant and must be reported.

Safety

• Do not hide preprocessing choices: they materially change velocity, confidence, and pseudotime.
• Do not oversell time: velocity_pseudotime and latent_time are model-derived orderings.
• Do not mix backend semantics: scVelo kinetics and VELOVI posteriors are not interchangeable labels.
• Keep visualization layers separated: R templates read figure_data/ and must not rerun the backend.

Dependencies

• Required:
  • scanpy
  • anndata
  • scvelo
• Optional by method:
  • scvi-tools
  • velovi

Citations

• Bergen V, et al. Generalizing RNA velocity to transient cell states through dynamical modeling. Nat Biotechnol. 2020.
• Gayoso A, et al. VELOVI: deep generative modeling of RNA velocity. 2024.