bio-reads-qc-mapping

name	bio-reads-qc-mapping
description	Ingest, QC, and map reads with reproducible outputs. Use for raw read processing and coverage stats.

Bio Reads QC Mapping

Ingest, QC, and map reads with reproducible outputs. Use for raw read processing and coverage stats.

Instructions

1. Parse sample sheet and validate inputs.
2. For short reads: run QC and adapter/quality trimming with bbduk or fastp v1.3.3+.
3. For long reads: trim adapters with Porechop_ABI (preferred; the original Porechop is unmaintained and ships stale adapter sets) or Pychopper for full-length cDNA. Filter by quality and length with filtlong v0.2.1.
4. Map reads and produce coverage tables:
   • Short reads, CPU: bbmap or bwa-mem2 v2.2.1+. Short reads, GPU node available: NVIDIA Parabricks fq2bam (wraps bwa-mem2 + GATK markdup; typically 3–4× faster than bwa-mem2 on 8 cores and up to ~80× over a 96-core CPU pipeline).
   • Long reads, CPU: minimap2 v2.30+. AVX-512 hardware: mm2-fast as a drop-in replacement (~1.8× speedup). GPU node available: mm2-gb or mm2-ax for CUDA-accelerated long-read alignment.
5. Record the tool, version, and any GPU device used in the run log.

Quick Reference

Task	Action
Run workflow	Follow the steps in this skill and capture outputs.
Validate inputs	Confirm required inputs and reference data exist.
Review outputs	Inspect reports and QC gates before proceeding.
Tool docs	See docs/README.md.

Input Requirements

Prerequisites:

• Tools available in the active environment (Pixi/conda/system). See docs/README.md for expected tools.
• Sample sheet and reads are available. Inputs:
• sample_sheet.tsv
• reads/*.fastq.gz
• reference.fasta (optional)

Output

• results/bio-reads-qc-mapping/trimmed_reads/
• results/bio-reads-qc-mapping/qc_reports/
• results/bio-reads-qc-mapping/mapping_stats.tsv
• results/bio-reads-qc-mapping/coverage.tsv
• results/bio-reads-qc-mapping/logs/

Quality Gates

• Post-QC read count sanity checks pass.
• Mapping rate meets project thresholds.
• On failure: retry with alternative parameters; if still failing, record in report and exit non-zero.
• Validate sample sheet schema and FASTQ integrity.

Examples

Example 1: Expected input layout

sample_sheet.tsv
reads/*.fastq.gz
reference.fasta (optional)

Troubleshooting

Issue: Missing inputs or reference databases Solution: Verify paths and permissions before running the workflow.

Issue: Low-quality results or failed QC gates Solution: Review reports, adjust parameters, and re-run the affected step.