genomics-qc

name: genomics-qc description: Load when running pre-alignment FASTQ quality control — Phred quality scores, Q20/Q30 rates, GC / N content, read-length distribution, adapter-contamination detection. Skip when working with already-aligned BAMs (use genomics-alignment) or when peak / variant files are the input (use the relevant downstream skill). version: 0.5.0 author: OmicsClaw license: MIT tags:

• genomics
• qc
• fastq
• phred
• adapter
• fastqc requires:
• pandas
• numpy

genomics-qc

When to use

The user has a raw FASTQ file (.fastq or .fastq.gz) and wants standard pre-alignment QC: total reads, mean Phred quality, Q20 / Q30 rates, GC / N content, mean read length, adapter contamination percentage, per-base quality profile. This skill mirrors a subset of FastQC / fastp metrics in pure Python.

It does NOT trim adapters or filter reads — it only measures. For BAM-level alignment QC use genomics-alignment.

Inputs & Outputs

Flow

1. Load FASTQ (--input <reads.fastq[.gz]>) or synthesise demo reads at output_dir/demo_reads.fastq (genomics_qc.py:170).
2. Stream up to --max-reads records (default 500_000); aggregate Phred / GC / N / length stats.
3. Detect adapter contamination via fixed adapter motif scan.
4. Write tables/qc_metrics.csv (genomics_qc.py:272) + tables/per_base_quality.csv (genomics_qc.py:279) + report.md + result.json.

Gotchas

• --max-reads defaults to 500 000 (genomics_qc.py:247). For very deep libraries this is a hard cap — increase it for full-flowcell QC. Reads beyond the cap are silently ignored.
• Empty FASTQ raises ValueError("No reads found in {fastq_path}") at genomics_qc.py:138. A truncated upload manifests as exit-1; check the file size first.
• --input REQUIRED unless --demo. genomics_qc.py:258 raises ValueError("--input required when not using --demo"); non-existent paths raise FileNotFoundError at :261.
• No trimming or filtering happens here. This is a pure measurement skill — to actually trim adapters or quality-filter, run fastp / Trimmomatic outside OmicsClaw before re-running this for post-trim QC.
• Phred encoding is assumed Phred+33. Old Solexa / Illumina 1.3+ Phred+64 files would mis-score; the script does NOT auto-detect encoding.
• Demo writes a synthetic FASTQ into output_dir. genomics_qc.py:170 writes demo_reads.fastq directly into the user-supplied output directory — re-running --demo overwrites silently.

Key CLI

# Demo (synthetic FASTQ)
python omicsclaw.py run genomics-qc --demo --output /tmp/qc_demo

# Real FASTQ
python omicsclaw.py run genomics-qc \
  --input reads.fastq.gz --output results/ \
  --max-reads 1000000

See also

• references/parameters.md — every CLI flag
• references/methodology.md — Phred / Q20 / Q30 definitions, adapter motifs
• references/output_contract.md — tables/qc_metrics.csv + per-base schema
• Adjacent skills: genomics-alignment (downstream — alignment QC after mapping), bulkrna-read-qc (parallel — RNA-seq-flavoured FASTQ QC), sc-qc (parallel — single-cell QC after mapping)