/sc-velocity

name: sc-velocity
description: Load when computing RNA velocity vectors on a scRNA AnnData with spliced / unspliced layers
  via scVelo (stochastic / dynamical / steady-state); dynamical mode additionally exports latent time.
  Skip when input lacks spliced+unspliced layers (use sc-velocity-prep); trajectory pseudotime ordering
  (use sc-pseudotime).
trigger: rna velocity, velocity, scvelo, spliced unspliced, cellular dynamics, velovi, velocity pseudotime
tags:
- singlecell
- scrna
- velocity
- rna-velocity
- scvelo
- latent-time
- kinetics

sc-velocity

Use from a step

velocity = load_skill("sc-velocity")
adata = velocity.velocity(read_input("velocity_ready.h5ad"), mode="stochastic",
                          n_jobs=4, random_state=0)
write_output(velocity.velocity_summary(adata), "tables/velocity_summary.csv")
write_output(velocity.top_velocity_genes(adata), "tables/top_velocity_genes.csv")
write_output(adata, "intermediate/adata_velocity.h5ad")

The function modifies the input, including scVelo gene filtering. `examples/example_step.py` uses `velocity_simulation`, a seeded kinetic simulation with spliced/unspliced layers. The old CLI demo is retained only for compatibility and does not establish biological velocity.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

`velocity(adata, *, mode: str='stochastic', n_jobs: int=4, random_state: int=0)`

Compute scVelo velocity in place, including its gene filtering.

Both spliced and unspliced count layers are required. The shared method filters/normalizes expression, explicitly constructs seeded neighbors, computes moments, velocity and its graph, plus latent time in dynamical mode. Fewer than five cells or genes, graph failures and latent-time failures raise errors; no placeholder outputs are created. Gene filtering modifies every aligned matrix. A failed call can leave partial preprocessing, so retry from a fresh input copy.

:param mode: stochastic (default), steady_state or dynamical. :param n_jobs: Dynamics worker budget, default 4; the shared small-data branch uses one worker. Graph workers follow scVelo's own settings. :param random_state: Neighbor seed, default 0. :returns: The same AnnData. Inspect velocity_diagnostics before interpretation. :raises ValueError: Layers, mode, worker budget or input dimensions are invalid. :raises RuntimeError: Velocity graph or dynamical latent-time computation fails. :raises ImportError: scvelo is unavailable.

`run_info(adata, *, keep: bool=True) -> dict`

Read the completed run's mode, seed and placeholder policy; empty after failure.

Completion does not establish biological fit validity. keep=False removes the record from uns.

`velocity_diagnostics(adata) -> dict`

Return zero/NaN and expressed-velocity-gene checks, not fit validation.

The API rejects placeholder fallbacks. For objects without a completed API run record, placeholder_fallback_used is unknown (None). These numerical checks do not establish biological fit validity.

`velocity_summary(adata) -> pd.DataFrame`

Return method, dimensions and latent-time availability as metric/value rows.

`velocity_cells_table(adata) -> pd.DataFrame`

Return cell_id, optional UMAP coordinates, velocity magnitude and latent time.

`top_velocity_genes(adata, *, n_top: int=40) -> pd.DataFrame`

Rank genes by mean absolute velocity and retain their signed mean.

`stream_figure(adata, *, basis: str='umap')`

Return a scVelo stream Figure; X_<basis> must already be present.

<!-- api:end -->

Methods and parameters

Modes are `stochastic` (default), `steady_state` and `dynamical`. The shared backend filters and normalizes expression, computes moments, velocity and its graph, and attempts latent time for dynamical mode. `random_state=0` explicitly seeds the neighbor graph before moments. `n_jobs=4` controls dynamics; the legacy small-data branch uses one worker and graph workers follow scVelo's settings.

The API never terminates its caller. The compatibility CLI drains its own loky workers and remaining descendants before exiting; it no longer kills the process group that may contain a notebook kernel.

Gotchas

• `_api.py:14` (`velocity`): scvelo 0.3.4's stochastic fit fails with NumPy 2.4

when its least-squares code assigns a one-element array to a scalar. The tested CI combination is scvelo 0.3.4 with NumPy 2.0.2.

• `velocity` can remove genes from X and all aligned layers (`_api.py:14`).
• Inspect `velocity_diagnostics(adata)`, not just the presence of a velocity layer.

It detects zero/NaN output, not biological validity (`_api.py:61`).

• Graph and dynamical latent-time failures raise errors with the backend

exception attached. The API and CLI do not replace them with identity graphs or uniform sequences (`_api.py:14`).

• Fewer than five cells or genes raise `ValueError` before fitting.

A failed call can leave partial preprocessing; retry from a fresh copy of the input (`_api.py:14`).

• Only dynamical mode attempts latent time. `stream_figure` requires an

existing display embedding such as X_umap (`_api.py:130`).

• Generate real splicing layers with `sc-velocity-prep`; copied or scaled

expression layers do not supply the required kinetic signal (`_api.py:14`).

Inputs & Outputs

Input AnnData must contain `layers["spliced"]` and `layers["unspliced"]`. The API returns the annotated object and table/Figure helpers.

CLI files include `processed.h5ad`, its `adata_with_velocity.h5ad` alias, `tables/velocity_summary.csv`, `tables/velocity_cells.csv`, `tables/top_velocity_genes.csv`, `report.md`, `result.json`, plots and figure-data manifests. Latent-time plots depend on that obs column; R-enhanced plots are optional.

Key CLI

python skills/singlecell/scrna/sc-velocity/sc_velocity.py --demo --output /tmp/sc_velocity_demo
python skills/singlecell/scrna/sc-velocity/sc_velocity.py --input velocity_ready.h5ad --mode