Sc Velocity Prep

---
# AUTO-GENERATED header from skill.yaml — do not edit by hand.
# Edit skill.yaml, then run: python scripts/generate_skill_md.py <skill_dir>
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).
version: 0.3.0
author: OmicsClaw
license: MIT
emoji: 🌀
tags:
- singlecell
- scrna
- velocity-prep
- velocyto
- starsolo
- spliced-unspliced
- kb-python
requires:
- anndata
- matplotlib
- numpy
- pandas
- scanpy
- scipy
- seaborn
---

# 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

<!-- AUTO-GENERATED from skill.yaml (interface) — do not edit by hand. Regenerate: python scripts/generate_skill_md.py <skill_dir> -->

**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/Summary.csv`
- `tables/barcodes.tsv`
- `tables/cell_metadata.csv`
- `tables/features.tsv`
- `tables/genes.tsv`
- `tables/metrics_summary.csv`
- `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`
- `3M-february-2018.txt`
- `737K-august-2016.txt`
- `Aligned.sortedByCoord.out.bam`
- `analysis_summary.txt`
- `multiqc_report.html`
- `possorted_genome_bam.bam`
- `processed.h5ad`
- `velocity_input.h5ad`
- `web_summary.html`
- `report.md`
- `result.json`
- Processed AnnData (`saves_h5ad`) — adds `layers`: `spliced`, `unspliced`, `ambiguous`

## 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 `--method` value here. Use the dedicated kb-python tooling outside OmicsClaw if you need that path.

## Key CLI

```bash
# 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)