sc-count

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 an 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

<!-- 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: .fastq, .fq, .h5ad
• FASTQ structure: valid first record; paired layout
• Directory layouts (any): paired-fastq, tenx-matrix, cellranger-output, starsolo-output, pseudoalign-output

Outputs

• tables/Summary.csv
• tables/backend_summary.csv
• tables/barcode_metrics.csv
• tables/barcodes.tsv
• tables/cell_metadata.csv
• tables/count_summary.csv
• tables/features.tsv
• tables/genes.tsv
• tables/metrics_summary.csv
• tables/simpleaf_t2g.tsv
• figures/barcode_rank.png
• figures/count_complexity_scatter.png
• figures/count_distributions.png
• 3M-february-2018.txt
• 737K-august-2016.txt
• Aligned.sortedByCoord.out.bam
• analysis_summary.txt
• cells_x_genes.barcodes.txt
• cells_x_genes.genes.txt
• multiqc_report.html
• possorted_genome_bam.bam
• processed.h5ad
• quants_mat_cols.txt
• quants_mat_rows.txt
• simpleaf_index.json
• standardized_input.h5ad
• web_summary.html
• 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:356 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:420 raises ValueError("STARsolo runs require an explicit --chemistryvalue such as10xv3.") 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:401, :423, :451 raise 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.
• Re-canonicalising-existing-output is detected by directory shape, not a flag. If --input points at a CellRanger output dir (e.g. one with outs/raw_feature_bc_matrix/), the skill skips counting and just imports the matrix. No flag separates the two paths; verify by inspecting result.json["data"]["execution"] (empty list = re-canonicalise; populated = backend invoked) or by reading tables/backend_summary.csv (lists the backend metrics only when the backend ran).

Key CLI

# Demo (synthetic FASTQ + CellRanger-shaped output)
python omicsclaw.py run sc-count --demo --output /tmp/sc_count_demo

# CellRanger over FASTQ
python omicsclaw.py run sc-count \
  --input fastq_dir/ --output results/ \
  --reference cellranger_transcriptome --threads 16

# STARsolo (requires explicit chemistry)
python omicsclaw.py run sc-count \
  --input fastq_dir/ --output results/ \
  --reference star_genome_dir --chemistry 10xv3 --whitelist barcodes.tsv

# Re-canonicalise an existing CellRanger output directory
python omicsclaw.py run sc-count \
  --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)