Sc Velocity

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.