/sc-count

name: sc-count
description: Load when turning scRNA FASTQ (or existing CellRanger/STARsolo/SimpleAF/kb-python output)
  into a downstream-ready AnnData. Skip when reads are already counted into AnnData (use sc-standardize-input);
  raw quality assessment only (use sc-fastq-qc).
trigger: Cell Ranger count, STARsolo count, fastq to adata, raw single-cell counting, generate count matrix
tags:
- singlecell
- scrna
- counting
- cellranger
- starsolo
- simpleaf
- kb-python

sc-count

Use from a step

This is CLI_ONLY: counting needs external tools and reference indexes.

from skills._sdk.notebook import run_cli

run_cli("sc-count", "--input", "data/sample_R1.fastq.gz",
        "--read2", "data/sample_R2.fastq.gz", "--method", "starsolo",
        "--reference", "/refs/star", "--chemistry", "10xv3",
        "--whitelist", "/refs/barcodes.tsv",
        inputs=["data/sample_R1.fastq.gz", "data/sample_R2.fastq.gz",
                "/refs/barcodes.tsv"])

Record the reference index version in the module README as well. The demo standardizes PBMC3k raw counts; it does not align or count reads. There is no `_api.py` for this skill.

When to use

The user has FASTQ files (or pre-existing tool output directories) and wants per-cell counts in OmicsClaw's canonical AnnData contract. Four backends share one CLI: `cellranger`, `starsolo`, `simpleaf`, `kb_python`. When passed a matching already-counted directory the skill re-canonicalises rather than re-counts. Pairs with `sc-fastq-qc` upstream (read QC) and `sc-multi-count` downstream (merging multiple samples).

Inputs & Outputs

**Inputs**

• Input kinds: `file`, `directory`
• Modalities: scrna
• File types: `.fastq`, `.fq`, compressed FASTQ, and backend-specific `.h5ad`
• FASTQ structure: valid first record; `paired` layout
• Directory layouts (any): `paired-fastq`, `tenx-matrix`, `cellranger-output`, `starsolo-output`, `pseudoalign-output`

**Outputs**

• `tables/backend_summary.csv`
• `tables/barcode_metrics.csv`
• `tables/count_summary.csv`
• `figures/barcode_rank.png`
• `figures/count_complexity_scatter.png`
• `figures/count_distributions.png`
• `processed.h5ad`
• `standardized_input.h5ad`
• `figures/manifest.json`, `figure_data/manifest.json`, plot-data CSV files
• `reproducibility/commands.sh`, `reproducibility/requirements.txt`
• Backend-specific files under `artifacts/` only when counting runs; BAM and HTML are not guaranteed.
• `report.md`
• `result.json`
• Processed AnnData (`saves_h5ad`)

Flow

1. Resolve `--input`; if it's an existing CellRanger / STARsolo / SimpleAF / kb-python output dir, re-canonicalise instead of running the backend. 2. Otherwise validate backend prerequisites (chemistry, reference, t2g for kb-python, whitelist for STARsolo). 3. Run the chosen backend against the FASTQ (and `--read2` if explicit). 4. Load the resulting matrix into AnnData; canonicalise (`layers["counts"]`, `adata.raw`, gene-name harmonisation). 5. Render barcode-rank + count-distribution figures. 6. Emit `processed.h5ad` + `report.md` + `result.json`.

Gotchas

• **Missing input path → hard fail.** `sc_count.py` raises `FileNotFoundError(f"Input path not found: {input_path}")`. Common when the FASTQ dir is on a network mount that has not been resolved at run time.
• **STARsolo requires explicit chemistry.** `sc_count.py` raises `ValueError("STARsolo runs require an explicit `--chemistry` value such as `10xv3`.")` when chemistry is left at the `auto` default. STARsolo currently supports `10xv2`, `10xv3`, and `10xv4`; pass one of those.
• **Backend prerequisites are validated up front.** `sc_count.py` raises `ValueError` for missing `--reference` (CellRanger/STARsolo/simpleaf), missing `--t2g` (kb-python), or unsupported `--chemistry` for STARsolo. No silent fallback to a different backend — pick a feasible one before invoking.
• **Choose the backend matching the existing output.** `sc_count.py:main` detects directory shape within the selected `--method`. `result.json["data"]["execution"]` is empty when no backend ran. `tables/backend_summary.csv` is always written and can be empty; imported output may already contain backend metrics.
• `sc_count.py:_recommended_reference_dir` names suggested reference locations, not bundled indexes. Supply references yourself. The simpleaf backend needs a configured `ALEVIN_FRY_HOME`; the installed simpleaf 0.24.0 failed without it during migration preflight. The demo does not validate external-tool setup.
• `sc_count.py:main` defaults to eight threads. A directory containing several FASTQ samples needs `--sample`.

Key CLI

# Demo (standardizes PBMC3k counts; no counting backend)
python skills/singlecell/scrna/sc-count/sc_count.py --demo --output /tmp/sc_count_demo

# CellRanger over FASTQ
python skills/singlecell/scrna/sc-count/sc_count.py \
  --input fastq_dir/ --output results/ \
  --reference cellranger_transcriptome --threads 16

# STARsolo (requires explicit chemistry)
python skills/singlecell/scrna/sc-count/sc_count.py \
  --input fastq_dir/ --output results/ \
  --method starsolo --reference star_genome_dir --chemistry 10xv3 --whitelist barcodes.tsv

# Re-canonicalise an existing CellRanger output directory
python skills/singlecell/scrna/sc-count/sc_count.py \
  --input cellranger_output_dir/ --output results/

See also

• `references/parameters.md` — every CLI flag and per-backend prerequisite
• `references/methodology.md` — backend selection guide, re-canonicalise vs re-run logic
• `references/output_contract.md` — `processed.h5ad` schema + table layouts
• Adjacent skills: `sc-fastq-qc` (upstream — read-quality check before counting), `sc-multi-count` (downstream — merge multiple sample outputs), `sc-standardize-input` (parallel — for AnnData from outside OmicsClaw)

Dependencies

Python packages this skill's script needs. They are not installed for you — check before a long run.

`anndata`, `matplotlib`, `numpy`, `pandas`, `scanpy`, `scipy`, `seab