ngs-quality-control

Files (10)

• SKILL.md
• README.md · agents/
• claude.yaml · agents/
• openai.yaml · agents/
• .gitkeep · assets/
• config.yaml
• README.md · references/
• fastqc-multiqc.md · references/
• batch_run.sh · scripts/
• run.sh · scripts/

SKILL.md (first lines)

# Skill: ngs-quality-control

## Use When

- The user wants to assess raw FASTQ read quality before downstream analysis.
- The user needs per-sample QC reports generated with FastQC.
- The user wants to aggregate QC results across multiple samples into a single summary with MultiQC.
- The user wants to check for adapter contamination, per-base quality drop-off, GC bias, or duplication levels before proceeding to trimming or alignment.

## Inputs

- Required:
  - FASTQ file(s) or a directory containing FASTQ files (`.fastq`, `.fq`, `.fastq.gz`, `.fq.gz`).
- Optional:
  - `--outdir DIR` — Output directory for reports (default: `fastqc_results`).
  - `--threads N` — Number of parallel threads for FastQC (default: 4).
  - `--multiqc-config FILE` — Custom MultiQC configuration file for report customization.
  - Additional FastQC modules to disable (pass via extra flags).

## Workflow

1. Validate that input FASTQ files exist and are readable.
2. Run FastQC on each FASTQ file, supporting parallel execution via `--threads`.
3. Collect all FastQC output directories (HTML reports and ZIP archives).
4. Run MultiQC to aggregate individual FastQC reports into a single HTML summary.
5. Parse key metrics from the results: per-base sequence quality, adapter content, sequence duplication levels, and per-sequence GC distribution.
6. Flag samples that fail critical quality thresholds (refer to `knowledge/sources/genomics/quality-thresholds.md` for threshold definitions).
7. Report summary statistics and the locations of the generated HTML reports.

## Output Contract

- **FastQC HTML report** — One per input FASTQ file (`<sample>_fastqc.html`).
- **FastQC ZIP archive** — One per input FASTQ file (`<sample>_fastqc.zip`), containing raw data and images.
- **MultiQC HTML report** — Aggregated summary at `<outdir>/multiqc/multiqc_report.html`.
- **Summary table** — Pass/Warn/Fail status per FastQC module per sample.
- **Flagged samples list** — Samples failing critical thresholds, with the specific modules that triggered the flag.

## Limits

- FastQC and MultiQC must be installed and available on `$PATH`.
- FastQC requires approximately 250 MB of memory per thread.
- This skill does not perform adapter trimming or quality filtering; use `ngs-read-preprocessing` for that purpose.
- MultiQC aggregation requires that all FastQC outputs are in a single directory tree.
- Very large cohorts (hundreds of samples) may require increased memory for MultiQC.
- Common failure cases:
  - Input files not in FASTQ format or corrupted gzip archives.
  - Insufficient disk space for FastQC output (HTML + ZIP per sample).
  - MultiQC version mismatch causing module parsing errors on newer FastQC output.

From Scientific-Tooling/structured-intelligence, MIT.

More from Scientific-Tooling/structured-intelligence