ngs-read-preprocessing

Files (10)

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

SKILL.md (first lines)

# Skill: ngs-read-preprocessing

## Use When

- The user wants to trim adapters from raw sequencing reads.
- The user needs to filter low-quality reads or bases before downstream alignment.
- The user wants to generate clean FASTQ files suitable for alignment or assembly.
- The user needs a per-sample HTML QC report showing before/after statistics.
- The user wants to perform polyG or polyX tail trimming for NextSeq/NovaSeq platforms.
- The user needs to apply minimum read length filtering after trimming.

## Inputs

- Required:
  - Input FASTQ R1 (`-i FILE`) — single-end read file or forward reads for paired-end.
- Optional:
  - Input FASTQ R2 (`-I FILE`) — reverse reads for paired-end sequencing.
  - `--outdir DIR` — Output directory (default: `fastp_results`).
  - `--threads N` — Number of worker threads (default: 4).
  - `--min-qual N` — Minimum qualified quality phred value for sliding window filtering (default: 15).
  - `--min-len N` — Minimum read length after trimming (default: 36 bp).
  - `--polyg` — Enable polyG tail trimming (recommended for NextSeq/NovaSeq two-color chemistry).
  - Adapter sequences — auto-detected by default; user may supply explicit sequences via additional fastp flags.
  - Additional fastp flags passed through as extra arguments.

## Workflow

1. Validate that input FASTQ files exist and are readable.
2. Detect single-end vs. paired-end mode from the provided inputs (`-i` only vs. `-i` and `-I`).
3. Run fastp with adapter auto-detection (or user-specified adapter sequences if provided).
4. Apply quality filtering using a sliding window approach (default: Q15 qualified quality threshold).
5. Apply length filtering to discard reads shorter than the minimum length (default: 36 bp).
6. Enable polyG tail trimming for NextSeq/NovaSeq platforms if `--polyg` is specified.
7. Generate an HTML report and JSON statistics file with detailed before/after metrics.
8. Report summary: reads before/after filtering, bases before/after, Q20/Q30 rates, and adapter trimming rate.

## Output Contract

- **Cleaned FASTQ file(s)** — Trimmed and filtered reads (`<sample>_trimmed.fastq.gz`; R1 and R2 for paired-end).
- **fastp HTML report** — Per-sample visual QC summary (`<sample>_fastp.html`).
- **fastp JSON report** — Machine-readable statistics (`<sample>_fastp.json`).
- **Summary statistics** — Reads in/out, bases in/out, Q20/Q30 rates before and after filtering, adapter detection/trimming rate.

## Limits

- fastp must be installed and available on `$PATH`.
- fastp is single-threaded by default; use `-w` / `--threads` to enable multi-threading (up to 16 threads).
- This skill does not perform read alignment; use `genome-read-alignment` or `rnaseq-read-alignment` for that purpose.
- This skill does not aggregate QC across multiple samples; use `ngs-quality-control` for multi-sample QC aggregation with MultiQC.
- UMI processing is supported by fastp but is not enabled by default; pass `--umi` and related flags as extra arguments if needed.
- Interleaved FASTQ input is not supported by the wrapper script; use fastp directly for interleaved input.
- Common failure cases:
  - Paired-end FASTQ files with mismatched read counts causing fastp to abort.
  - Incorrect adapter sequences provided, leading to untrimmed reads.
  - Disk full during output writing, producing truncated FASTQ files.

From Scientific-Tooling/structured-intelligence, MIT.

More from Scientific-Tooling/structured-intelligence