sc-fastq-qc

name	sc-fastq-qc
description	Load when checking raw single-cell FASTQ read quality (Phred / GC / adapter / length) before counting. Skip when reads are already counted (use sc-qc) or for bulk FASTQ (use bulkrna-read-qc).
version	0.3.0
author	OmicsClaw
license	MIT
tags	["singlecell","scrna","fastq","qc","read-quality"]
requires	["pandas","matplotlib"]

sc-fastq-qc

When to use

The user has raw scRNA-seq FASTQ files (one or more, or a directory of samples) and wants per-file / per-sample / per-base quality summaries before running sc-count or cellranger. Uses FastQC + MultiQC when those tools are installed; falls back to a stable Python-only summary otherwise so the skill always returns something useful.

Inputs & Outputs

Input	Format	Required
Raw scRNA reads	.fastq / .fastq.gz (single file or directory)	yes (unless --demo)

Output	Path	Notes
Per-file table	tables/fastq_per_file_summary.csv	one row per FASTQ
Per-sample table	tables/fastq_per_sample_summary.csv	aggregated by sample
Per-base table	tables/fastq_per_base_quality.csv	quality vs read position
Quality figures	figures/fastq_q30_summary.png, figures/per_base_quality.png, figures/fastq_file_quality.png, figures/fastq_read_structure.png	all four always rendered
Report	report.md + result.json	always written

Flow

1. Discover FASTQ files from --input (single file or directory).
2. If fastqc is on $PATH, run it; if multiqc is on $PATH, run that too.
3. In parallel run a Python-only fallback that samples up to --max-reads per FASTQ for Phred / GC / adapter / length.
4. Merge tool output + fallback into per-file / per-sample / per-base tables.
5. Render quality + adapter / GC diagnostic figures.
6. Emit report.md + result.json.

Gotchas

• --max-reads 20000 (default) caps the Python-fallback path only. When FastQC is available the full FASTQ is processed; when not, only the first 20K reads per file are sampled. Sampling depth is recorded per file in tables/fastq_per_file_summary.csv; bump --max-reads if a FASTQ has high variance across the file.
• --r-enhanced is accepted but produces no R plots. This skill emits Python figures only. Pass freely, expect no R Enhanced output.
• Per-figure status: "rendered" is local, not global. The result.json carries a status field per figure (e.g. figures.per_base_quality.status == "rendered"). All four panels are emitted unconditionally (sc_fastq_qc.py:430-433), so absence of an entry typically means upstream tool failure rather than a configuration choice — inspect summary.warnings before assuming a panel was suppressed.

Key CLI

# Demo (built-in synthetic FASTQ)
python omicsclaw.py run sc-fastq-qc --demo --output /tmp/sc_fastq_qc_demo

# Single-file with paired-end
python omicsclaw.py run sc-fastq-qc \
  --input sample_R1.fastq.gz --read2 sample_R2.fastq.gz --output results/

# Directory of samples, deeper sampling for the Python fallback
python omicsclaw.py run sc-fastq-qc \
  --input fastq_dir/ --output results/ --max-reads 100000 --threads 8

See also

• references/parameters.md — every CLI flag and tuning hint
• references/methodology.md — FastQC integration + Python fallback rationale
• references/output_contract.md — table column schemas + figure roles
• Adjacent skills: sc-count (next step — FASTQ → AnnData), bulkrna-read-qc (bulk RNA-seq variant), sc-qc (downstream count-matrix QC)