Sc Count

Input Formats

Data / State Requirements

Beginner Setup Hint

If the user is missing reference assets, guide them to either:

1. pass explicit local paths such as --reference, --whitelist, or --t2g
2. or place files under:
   • resources/singlecell/references/cellranger/
   • resources/singlecell/references/starsolo/
   • resources/singlecell/references/simpleaf/
   • resources/singlecell/references/kb/
   • resources/singlecell/references/whitelists/

Download guidance:

• Cell Ranger reference: official 10x reference release pages
• STARsolo: build a STAR genome directory from a matching FASTA / GTF
• STARsolo whitelist: official 10x Cell Ranger barcode files such as 3M-february-2018.txt
• kb-python: keep both the kallisto index and the matching t2g

Workflow

1. Load: detect whether the input is FASTQ or an existing count-output directory.
2. Validate: enforce one chosen sample and backend-specific requirements.
3. Run method: launch the selected backend when needed, or import existing outputs directly.
4. Persist results: load the filtered matrix, standardize it into the OmicsClaw AnnData contract, and preserve backend artifact paths.
5. Visualize / summarize: generate barcode-rank and count-distribution plots plus summary tables.
6. Report: write README.md, report.md, result.json, and the reproducibility bundle.

CLI Reference

oc run sc-count --input fastqs/ --method cellranger --reference /path/to/refdata-gex-GRCh38-2020-A --output results/
oc run sc-count --input fastqs/ --method starsolo --reference /path/to/star_index --chemistry 10xv3 --whitelist /path/to/3M-february-2018.txt --output results/
oc run sc-count --input fastqs/ --method simpleaf --reference /path/to/simpleaf_index --chemistry 10xv3 --output results/
oc run sc-count --input fastqs/ --method kb_python --reference /path/to/kallisto.idx --t2g /path/to/t2g.txt --chemistry 10xv3 --output results/
oc run sc-count --input sample_count/ --method cellranger --output results/
python skills/singlecell/scrna/sc-count/sc_count.py --demo --output /tmp/sc_count_demo

Example Queries

• "把这些单细胞 FASTQ 先跑成 count matrix"
• "用 Cell Ranger 跑 10x 数据然后直接转 h5ad"
• "用 STARsolo 产出能接 OmicsClaw 的 adata"
• "用 simpleaf 跑 10x FASTQ 然后直接转 h5ad"
• "把 kb-python 的输出接到后面的 scRNA 技能"

Algorithm / Methodology

Cell Ranger Path

1. FASTQ grouping: infer one target sample from the input path.
2. Run Cell Ranger: execute cellranger count with --nosecondary and BAM output kept on.
3. Import filtered matrix: load the filtered feature-barcode matrix into AnnData.
4. Standardize output: create layers['counts'], stabilize names, and record OmicsClaw input-contract metadata.

STARsolo Path

1. FASTQ grouping: infer one target sample from the input path.
2. Run STARsolo: execute a 10x-oriented CB_UMI_Simple wrapper with EmptyDrops-style cell calling.
3. Import filtered matrix: load Solo.out/Gene/filtered.
4. Standardize output: create layers['counts'] and record the same OmicsClaw contract as the Cell Ranger path.

SimpleAF / Alevin-fry Path

1. FASTQ grouping or import: infer one sample or import an existing simpleaf output.
2. Run backend: execute simpleaf quant when needed.
3. Import result: read an existing H5AD or matrix output.
4. Standardize output: create the same OmicsClaw count handoff contract.

kb-python Path

1. FASTQ grouping or import: infer one sample or import an existing kb output.
2. Run backend: execute kb count when needed.
3. Import result: read an existing H5AD or matrix output.
4. Standardize output: create the same OmicsClaw count handoff contract.

Key parameters:

Current OmicsClaw behavior: all non-Cell Ranger methods are intentionally scoped to mainstream 10x-style droplet geometry first. Complex custom chemistries remain deferred.

Visualization Contract

1. Python standard gallery: barcode-rank and count-distribution plots.
2. Figure-ready exports: count summary and per-barcode tables under figure_data/.
3. Gallery manifest: figures/manifest.json records the standard counting gallery.

Output Structure

output_directory/
├── README.md
├── report.md
├── result.json
├── processed.h5ad
├── figures/
│   ├── barcode_rank.png
│   └── count_distributions.png
│   ├── count_complexity_scatter.png
│   └── manifest.json
├── tables/
│   ├── count_summary.csv
│   ├── barcode_metrics.csv
│   └── backend_summary.csv
├── figure_data/
│   ├── manifest.json
│   ├── count_summary.csv
│   └── barcode_metrics.csv
├── artifacts/
│   ├── cellranger/
│   ├── starsolo/
│   ├── simpleaf/
│   └── kb_python/
└── reproducibility/
    ├── analysis_notebook.ipynb
    ├── commands.sh
    └── requirements.txt

Reproducibility Contract

• The filtered count matrix is always converted into the OmicsClaw AnnData input contract.
• Backend-specific raw outputs remain preserved under artifacts/ for methods such as CellBender or RNA-velocity preparation.

Knowledge Companions

• knowledge_base/knowhows/KH-sc-count-guardrails.md: short execution guardrails for import-vs-run decisions and backend boundaries.
• knowledge_base/skill-guides/singlecell/sc-count.md: longer operator guide for count-method choice and downstream hand-off.

Dependencies

Required:

• Python 3
• scanpy, anndata, pandas, numpy

Optional but method-specific:

• cellranger
• STAR
• simpleaf
• kb

Environment Management

• Python extras:
  • pip install -e ".[singlecell-upstream]"
• External tools that OmicsClaw does not auto-install:
  • cellranger
  • STAR
  • simpleaf
  • kb

Recommended user guidance:

• Do not auto-install counting backends during a normal run.
• If a backend binary is missing, prompt the user to install it explicitly in the active environment or module system.
• Reference files are also user-managed resources; OmicsClaw should guide users to resources/singlecell/references/... or accept explicit local paths, but should not silently download large references during execution.

CLI Parameters

R Enhanced Plots

This skill has no R Enhanced plots. The --r-enhanced flag is accepted for CLI consistency but produces no additional output.

Special Requirements

Reference Files

Each backend requires its own reference assets. OmicsClaw does not download references automatically.

Place reference assets under resources/singlecell/references/<backend>/ for auto-detection, or pass explicit paths via --reference.

Direct Import (No Re-run)

If a Cell Ranger or STARsolo run has already completed, pass the existing output directory as --input and omit --reference. The wrapper imports the filtered matrix directly without re-running the backend.

# Cell Ranger — run from FASTQ
python omicsclaw.py run sc-count \
  --input fastqs/ --method cellranger \
  --reference /path/to/refdata-gex-GRCh38-2020-A \
  --output results/

# STARsolo — run from FASTQ
python omicsclaw.py run sc-count \
  --input fastqs/ --method starsolo \
  --reference /path/to/star_index \
  --chemistry 10xv3 \
  --whitelist /path/to/3M-february-2018.txt \
  --output results/

# kb-python — run from FASTQ
python omicsclaw.py run sc-count \
  --input fastqs/ --method kb_python \
  --reference /path/to/kallisto.idx \
  --t2g /path/to/t2g.txt \
  --chemistry 10xv3 \
  --output results/

# Import existing Cell Ranger output
python omicsclaw.py run sc-count \
  --input sample_count/ --method cellranger \
  --output results/

Workflow Position

• Optional upstream step: sc-fastq-qc for read-level quality assessment before counting
• Usual next step: sc-qc for quality assessment, or sc-multi-count if merging multiple samples