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 (go straight to sc-velocity) or for any non-velocity preprocessing (use sc-preprocessing).
version	0.3.0
author	OmicsClaw
license	MIT
tags	["singlecell","scrna","velocity-prep","velocyto","starsolo","spliced-unspliced","kb-python"]
requires	["anndata","numpy","pandas"]

sc-velocity-prep

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

Input	Format	Required
Cell Ranger run dir / STARsolo dir / FASTQ dir / .loom	path	yes (unless --demo)
GTF	.gtf (--gtf)	required for BAM-backed velocyto
STAR index	dir (--reference)	required for FASTQ-backed STARsolo
Chemistry	10xv2 / 10xv3 / 10xv4 (--chemistry)	required for FASTQ STARsolo
Optional base AnnData	.h5ad (--base-h5ad)	merge layers into existing object

Output	Path	Notes
Velocity-ready AnnData	processed.h5ad	adds layers["spliced"], layers["unspliced"], layers["ambiguous"]
Layer totals	tables/velocity_layer_summary.csv	molecules per layer
Top genes	tables/top_velocity_genes.csv	highest-abundance velocity genes
Figures	figures/velocity_layer_summary.png, figures/velocity_layer_fraction.png, figures/velocity_gene_balance.png, figures/velocity_top_genes_stacked.png	always
Report	report.md + result.json	always

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:397 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:437 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:444 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:458 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:100 is documented as "with a local fallback for index-name quirks"; :112 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:373 calls parser.error("--input required when not using --demo"). Once provided, :376 raises FileNotFoundError(f"Input path not found: {input_path}") for a missing path.
• --method choices are exactly velocyto / starsolo. sc_velocity_prep.py:346 declares the choices via argparse; kb-python is mentioned in upstream-prep docstrings but is not a valid value here. Use the dedicated kb-python tooling outside OmicsClaw if you need that path.

Key CLI

# Demo (synthetic loom; does NOT exercise velocyto / STARsolo)
python omicsclaw.py run sc-velocity-prep --demo --output /tmp/sc_velo_prep_demo

# velocyto from a Cell Ranger run (BAM-backed)
python omicsclaw.py run sc-velocity-prep \
  --input /data/cellranger_run/ --output results/ \
  --method velocyto --gtf /refs/Homo_sapiens.GRCh38.gtf

# Load existing STARsolo Velocyto output directly
python omicsclaw.py run sc-velocity-prep \
  --input /data/starsolo_run/ --output results/ \
  --method starsolo

# Re-run STARsolo from FASTQ (chemistry must be explicit)
python omicsclaw.py run sc-velocity-prep \
  --input /data/fastqs/ --output results/ \
  --method starsolo --reference /refs/star_index --chemistry 10xv3

# Merge velocity layers into an existing processed AnnData
python omicsclaw.py run sc-velocity-prep \
  --input /data/cellranger_run/ --output results/ \
  --method velocyto --gtf /refs/Homo_sapiens.GRCh38.gtf \
  --base-h5ad /path/to/clustered.h5ad

See also

• references/parameters.md — every CLI flag, per-backend tunables
• references/methodology.md — when velocyto vs STARsolo wins; whitelist conventions
• references/output_contract.md — layers["spliced"] / layers["unspliced"] / layers["ambiguous"] schema
• Adjacent skills: sc-count / sc-multi-count (upstream — produce the Cell Ranger / STARsolo output this skill consumes), sc-velocity (downstream — consumes layers["spliced"] + layers["unspliced"]), sc-clustering (parallel — pass clustered output as --base-h5ad to keep clusters when adding velocity layers)