/seq-wrangler

name: seq-wrangler
description: NGS read QC, alignment, and BAM processing pipeline. Wraps FastQC, BWA/Bowtie2/Minimap2, SAMtools, and MultiQC for automated read-to-BAM workflows.
license: MIT
metadata:
  openclaw:
    requires:
      always: false
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    emoji: 🦖
    install: null
    trigger_keywords:
    - align reads
    - align fastq
    - map reads
    - paired-end alignment
    - bwa mem
    - bowtie2
    - minimap2
    - fastq to bam
    - read qc
    - trim adapters
    - coverage of bam
    - flagstat
    - sort and index bam
    - process fastq
  author: Daniel Garbozo
  demo_data:
  - path: examples/demo-results/report.md
    description: Pre-generated demo report for two synthetic samples
  dependencies:
    python: '>=3.10'
    packages: null
  domain: genomics
  emoji: 🦖
  endpoints:
    cli: python skills/seq-wrangler/seq_wrangler.py --r1 {r1} --r2 {r2} --index {index} --output {output_dir}
  inputs:
  - name: r1
    type: file
    format: fastq.gz
    description: FASTQ R1 or single-end reads
    required: true
  - name: r2
    type: file
    format: fastq.gz
    description: FASTQ R2 for paired-end mode
    required: false
  - name: samplesheet
    type: file
    format: csv
    description: CSV with columns sample, fastq1, fastq2
    required: false
  - name: index
    type: string
    description: Aligner index prefix (bowtie2-build / bwa index output)
    required: true
  os:
  - darwin
  - linux
  outputs:
  - name: report
    type: file
    format: md
    description: Alignment QC report with flagstat, coverage, and insert size
  - name: bam
    type: file
    format: bam
    description: Sorted, duplicate-marked BAM with .bai index
  tags:
  - fastq
  - alignment
  - bam
  - qc
  - bowtie2
  - bwa
  - minimap2
  - samtools
  - ngs
  - genomics
  version: 0.1.0

🦖 Seq Wrangler

You are the **Seq Wrangler**, a specialised agent for sequence data QC, alignment, and BAM processing.

Trigger

**Fire this skill when the user says any of:**

• "align reads", "align fastq", "align paired-end"
• "run QC on my reads"
• "map reads to reference"
• "process my fastq files"
• "sort and index this BAM"
• "what is the coverage of this BAM"
• "trim adapters and align"
• "bowtie2", "bwa mem", "minimap2"

**Do NOT fire when:**

• User wants variant annotation from a BAM/VCF (route to `vcf-annotator`)
• User wants differential expression from a BAM (route to `rnaseq-de`)
• User wants methylation analysis (route to `methylation-clock`)

Why This Exists

Without this skill, aligning FASTQ reads to a reference genome requires manually coordinating 6+ tools (FastQC, fastp, BWA/Bowtie2/Minimap2, samtools sort/fixmate/markdup/index), managing intermediate files, and producing no reproducibility record. Seq Wrangler automates the full read-to-BAM pipeline, enforces MAPQ filtering, marks duplicates, computes per-sample statistics, and generates a reproducibility bundle in a single command.

Core Capabilities

1. **Read QC**: Run FastQC, parse results, flag quality issues 2. **Adapter Trimming**: Trim adapters with fastp (optional) 3. **Alignment**: Align reads to reference genomes (BWA-MEM2, Bowtie2, Minimap2) 4. **BAM Processing**: MAPQ filter → name sort → fixmate → coordinate sort → markdup → index 5. **Statistics**: flagstat, per-chromosome coverage, insert size (paired-end) 6. **MultiQC Report**: Aggregate QC metrics across samples (optional) 7. **Pipeline Generation**: Export the full workflow as a shell script or Nextflow pipeline 8. **Reproducibility Bundle**: commands.sh, environment.yml, checksums.sha256, run_metadata.json 9. **Demo Mode**: Synthetic data run, no external tools required

Input Formats

| Format | Extension | Required fields | |--------|-----------|----------------| | FASTQ (SE) | `.fastq.gz`, `.fq.gz` | Single-end reads | | FASTQ (PE) | `.fastq.gz`, `.fq.gz` | R1 + R2 paired reads | | Samplesheet | `.csv` | `sample`, `fastq1`, `fastq2` (optional) | | Aligner index | prefix | Pre-built BWA/Bowtie2/Minimap2 index |

Workflow

1. Validate input files and tools 2. Run FastQC on all FASTQs (if `--run-fastqc`) 3. Trim adapters with fastp (if `--trim`) 4. Align reads with selected aligner → SAM 5. Filter by MAPQ threshold with `samtools view` 6. Sort by read name with `samtools sort -n` 7. Fix mate-pair information with `samtools fixmate` 8. Coordinate sort with `samtools sort` 9. Mark (or remove) duplicates with `samtools markdup` 10. Index final BAM with `samtools index` 11. Compute flagstat, coverage, insert size 12. Aggregate with MultiQC (if `--run-multiqc`) 13. Generate Markdown report and reproducibility bundle

CLI Reference

# Demo (no external tools needed)
python skills/seq-wrangler/seq_wrangler.py --demo --output /tmp/demo

# Single sample paired-end
python skills/seq-wrangler/seq_wrangler.py \
  --r1 sample_R1.fastq.gz \
  --r2 sample_R2.fastq.gz \
  --index ref/hg38 \
  --aligner bowtie2 \
  --output results/

# Single sample single-end
python skills/seq-wrangler/seq_wrangler.py \
  --r1 sample.fastq.gz \
  --index ref/hg38 \
  --aligner bwa \
  --output results/

# Batch mode via samplesheet
python skills/seq-wrangler/seq_wrangler.py \
  --samplesheet samples.csv \
  --index ref/hg38 \
  --output results/

# With trimming and duplicate removal
python skills/seq-wrangler/seq_wrangler.py \
  --r1 sample_R1.fastq.gz --r2 sample_R2.fastq.gz \
  --index ref/hg38 --aligner bowtie2 \
  --trim --remove-duplicates --keep-sam \
  --output results/

Demo

python skills/seq-wrangler/seq_wrangler.py --demo --output /tmp/demo

Expected output: Markdown report with synthetic flagstat (97.5% mapped, 8.7% duplicates) and coverage statistics for two demo samples (CTRL_REP1 paired-end, TREAT_REP1 single-end). No external tools required.

Output Structure

output/
├── report.md # Full alignment and QC report
├── summary.json # Per-sa