/sc-velocity-prep

name: sc-velocity-prep
description: Load when generating spliced / unspliced layers from Cell Ranger BAM, FASTQ, STARsolo output,
  or velocyto loom — the prerequisite for sc-velocity. Skip when AnnData already has spliced+unspliced
  layers (use sc-velocity); any non-velocity preprocessing (use sc-preprocessing).
trigger: RNA velocity prep, prepare spliced unspliced layers, velocyto, starsolo velocyto, velocity-ready AnnData
tags:
- singlecell
- scrna
- velocity-prep
- velocyto
- starsolo
- spliced-unspliced

sc-velocity-prep

Use from a step

This is CLI_ONLY: it runs external preparation tools or imports their files.

from skills._sdk.notebook import run_cli

run_cli("sc-velocity-prep", "--input", "data/velocity.loom",
        "--base-h5ad", "data/clustered.h5ad",
        inputs=["data/velocity.loom", "data/clustered.h5ad"])

The demo splits PBMC3k counts into fixed 82% spliced, 14% unspliced and 4% ambiguous layers. It checks packaging, not velocity biology or external tool installation. There is no `_api.py` for this skill.

When to use

The user has raw Cell Ranger output (BAM + barcodes), STARsolo output, or paired FASTQs and needs an AnnData with `layers["spliced"]` / `layers["unspliced"]` (and optional `layers["ambiguous"]`) before running `sc-velocity`. Two backends:

• `velocyto` (default) — runs `velocyto run` against a Cell Ranger BAM

using a GTF. Produces a `.loom` and reads it back into AnnData.

• `starsolo` — re-runs alignment from FASTQ via STARsolo with the

Velocyto solo subworkflow, or loads existing STARsolo Velocyto output directly when detected.

`--base-h5ad` lets you merge the velocity layers into an already-processed AnnData (preserves `obs` / `obsm` / clustering).

For velocity estimation itself use `sc-velocity`. For non-velocity scRNA preprocessing use `sc-preprocessing`.

Inputs & Outputs

**Inputs**

• Input kinds: `file`, `directory`
• Modalities: scrna
• File types: `.loom`, `.fastq`, `.fq`
• FASTQ structure: valid first record; `paired` layout
• Directory layouts (any): `paired-fastq`, `cellranger-output`, `starsolo-velocity`

**Outputs**

• `tables/top_velocity_genes.csv`
• `tables/velocity_layer_summary.csv`
• `figures/velocity_gene_balance.png`
• `figures/velocity_layer_fraction.png`
• `figures/velocity_layer_summary.png`
• `figures/velocity_top_genes_stacked.png`
• `processed.h5ad`
• `velocity_input.h5ad`
• `figures/manifest.json`, `figure_data/manifest.json`, plot-data CSV files
• `reproducibility/commands.sh`, `reproducibility/requirements.txt`
• Conditional backend artifacts under `artifacts/`; imported loom/STARsolo inputs do not create new BAM files.
• `report.md`
• `result.json`
• Processed AnnData — `spliced`, `unspliced` layers; `ambiguous` only when supplied by the source

Flow

1. Resolve `--input` (Cell Ranger dir / STARsolo dir / FASTQ / `.loom`). 2. For `velocyto`: locate BAM + barcodes, validate `--gtf` (or auto-pick from `resources/singlecell/references/gtf/`), run `velocyto run`, load `.loom`. 3. For `starsolo`: detect existing STARsolo Velocyto output and load directly, OR re-run STARsolo Velocyto with `--reference` + `--chemistry` + auto-detected `--whitelist`. 4. Optionally merge layers into `--base-h5ad`. 5. Compute layer totals (`tables/velocity_layer_summary.csv`) and top-gene balance. 6. Save `processed.h5ad`, tables, figures, `report.md`, `result.json`.

Gotchas

• **BAM-backed velocyto needs a GTF.** `sc_velocity_prep.py` raises `ValueError("BAM-backed velocyto preparation requires a GTF file. Pass `--gtf /abs/path/to/genes.gtf`, or keep one under `resources/singlecell/references/gtf/`. ...")`. Auto-detection only fires if a project-local GTF lives at the recommended path.
• **FASTQ-backed STARsolo needs a STAR index AND explicit chemistry.** `sc_velocity_prep.py` raises `ValueError("FASTQ-backed STARsolo velocity preparation requires a STAR genome directory. ...")` if `--reference` is missing and nothing's at `resources/singlecell/references/starsolo/`. `sc_velocity_prep.py` raises `ValueError("FASTQ-backed STARsolo velocity preparation requires an explicit `--chemistry`.")` when `--chemistry auto` is left as the default — STARsolo cannot infer 10x v2 vs v3 vs v4 from FASTQ alone.
• **STARsolo whitelist is auto-guessed; missing → hard fail.** `sc_velocity_prep.py` raises `ValueError("Could not infer a compatible STARsolo whitelist. Pass `--whitelist /abs/path/to/3M-february-2018.txt`, or keep the whitelist under `resources/singlecell/references/whitelists/`. ...")`. The guesser uses the reference path + chemistry; a non-standard reference layout breaks it.
• **STARsolo Velocyto matrix loader has a fallback for index-name quirks.** `sc_velocity_prep.py` is documented as "with a local fallback for index-name quirks"; `_load_starsolo_velocyto_dir_safe` raises `FileNotFoundError(f"Could not locate STARsolo Velocyto matrices under: {path}")` when nothing matches even with the fallback. Common when STARsolo finished partial / was killed mid-run.
• **`--input` mandatory unless `--demo` (parser.error, exit code 2).** `sc_velocity_prep.py` calls `parser.error("--input required when not using --demo")`. Once provided, `main` raises `FileNotFoundError(f"Input path not found: {input_path}")` for a missing path.
• **`--method` choices are exactly `velocyto` / `starsolo`.** `sc_velocity_prep.py` declares the choices via argparse; `kb-python` is mentioned in upstream-prep docstrings but is not a valid `--method` value here. Use the dedicated kb-python tooling outside OmicsClaw if you need that path.
• `sc_velocity_prep.py:main` defaults to eight threads. Reference directories named in error messages are suggestions, not shipped assets. Verify the `velocyto` command can import before a long BAM run; migration preflight found `undefined symbol: __log10_finite` in the installed copy despite its presence on PATH.
• `sc_velocity_prep.py:main` writes a new `.raw` snapshot and records `.X` as raw counts