🦖 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
- Read QC: Run FastQC, parse results, flag quality issues
- Adapter Trimming: Trim adapters with fastp (optional)
- Alignment: Align reads to reference genomes (BWA-MEM2, Bowtie2, Minimap2)
- BAM Processing: MAPQ filter → name sort → fixmate → coordinate sort → markdup → index
- Statistics: flagstat, per-chromosome coverage, insert size (paired-end)
- MultiQC Report: Aggregate QC metrics across samples (optional)
- Pipeline Generation: Export the full workflow as a shell script or Nextflow pipeline
- Reproducibility Bundle: commands.sh, environment.yml, checksums.sha256, run_metadata.json
- 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, fastq_1, fastq_2 (optional) |
| Aligner index |
prefix |
Pre-built BWA/Bowtie2/Minimap2 index |
Workflow
- Validate input files and tools
- Run FastQC on all FASTQs (if
--run-fastqc)
- Trim adapters with fastp (if
--trim)
- Align reads with selected aligner → SAM
- Filter by MAPQ threshold with
samtools view
- Sort by read name with
samtools sort -n
- Fix mate-pair information with
samtools fixmate
- Coordinate sort with
samtools sort
- Mark duplicates with
samtools markdup (removes them with -r if --remove-duplicates)
- Index final BAM with
samtools index
- Compute flagstat, coverage, insert size
- Aggregate with MultiQC (if
--run-multiqc)
- 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/
| Flag |
Description |
Default |
--r1 |
FASTQ R1 or single-end FASTQ |
— |
--r2 |
FASTQ R2 for paired-end |
— |
--sample-name |
Sample name for single-sample mode |
— |
--samplesheet |
CSV with columns sample,fastq_1,fastq_2 |
— |
--index |
Aligner index prefix |
required unless --demo |
--aligner |
bwa, bowtie2, or minimap2 |
bwa |
--genome-build |
GRCh38 or GRCh37 (metadata only) |
GRCh38 |
--output |
Output directory |
required |
--threads |
Number of threads |
CPU count − 1 |
--mapq |
MAPQ filter threshold |
20 |
--trim |
Run fastp trimming before alignment |
off |
--remove-duplicates |
Remove duplicates with samtools markdup -r instead of only marking them |
off |
--keep-sam |
Keep intermediate SAM files |
off |
--run-fastqc |
Run FastQC if available |
off |
--run-multiqc |
Run MultiQC aggregation if available |
off |
--demo |
Run with synthetic data, no tools needed |
off |
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-sample statistics as JSON
├── bam/
│ └── sample_sorted.bam # Final sorted, markdup BAM
│ └── sample_sorted.bam.bai # BAM index
├── alignment/
│ └── sample.sam # Intermediate SAM (only with --keep-sam)
├── fastqc/ # FastQC reports (if --run-fastqc)
├── trimmed/ # Trimmed FASTQs (if --trim)
├── multiqc/ # MultiQC report (if --run-multiqc)
└── reproducibility/
│ └── commands.sh # Exact command to reproduce this run
│ └── environment.yml # Conda environment spec
│ └── checksums.sha256 # SHA-256 of all input files
│ └── run_metadata.json # Full run parameters and timestamp
Dependencies
Required:
samtools (BAM manipulation)
- One of:
bwa, bowtie2, or minimap2 (alignment)
Optional:
fastqc: per-sample read QC
fastp: adapter trimming
multiqc: aggregated QC report
Install via conda:
conda install -c bioconda samtools bowtie2 bwa minimap2 fastqc fastp multiqc
Gotchas
Memory for samtools sort: Uses 2G RAM per thread by default. On machines
with <8G RAM, use --threads 2 or --threads 3 to avoid OOM errors.
python3 vs python on Windows: Tests use sys.executable instead of
python3 for cross-platform compatibility. On Windows, python3 may not
exist in PATH.
Index prefix vs file: --index expects the aligner index prefix
(e.g. hg38_chr22), not a .fa or .bt2 file path. Build with
bowtie2-build genome.fa prefix first.
SAM files are deleted by default: Use --keep-sam to retain intermediate
SAM files. They can be 10x larger than the final BAM.
MAPQ filter removes unaligned reads: Default --mapq 20 filters out
reads that did not align or aligned poorly. Lower this value if you expect
low-quality data.
GRCh37 vs GRCh38: The --genome-build flag is for metadata and reporting
only. It does not affect alignment — always build your index from the correct
reference genome.
Agent Boundary
The agent (LLM) dispatches the FASTQ files and explains results.
The skill (Python) executes all tool calls and generates files.
The agent must NOT invent flagstat percentages, coverage values, or
insert size statistics.
Safety
- Local-first: no data is uploaded to external servers
- Network calls: none
- Disclaimer: Seq Wrangler is a research and educational tool. Results must be validated before use in clinical or production settings
- No hardcoded credentials or absolute paths
- MAPQ filtering applied by default (≥20) to reduce spurious alignments
Integration with Bio Orchestrator
Trigger conditions:
- User provides FASTQ files and asks for alignment or QC
- Keywords:
align, fastq, bam, coverage, paired-end, bowtie2, bwa
Chaining partners:
- →
rnaseq-de: pass final BAM for differential expression
- →
methylation-clock: pass BAM for methylation analysis
- →
equity-scorer: pass BAM for population equity metrics
- →
acmg: pass aligned BAM for variant calling upstream
Example Queries
- "Run QC on these FASTQ files and show me the quality summary"
- "Align paired-end reads to GRCh38 and sort the output BAM"
- "What is the mean coverage of this BAM file?"
- "Trim adapters and re-align these reads"
- "Process this samplesheet of 10 samples with bowtie2 and remove duplicates"
- "Run the seq-wrangler demo so I can see what the output looks like"
- "Align these single-end reads with minimap2 and keep the SAM file"
Citations
- Li H. et al. (2009) The Sequence Alignment/Map format and SAMtools. Bioinformatics
- Langmead B. & Salzberg S. (2012) Fast gapped-read alignment with Bowtie 2. Nature Methods
- Li H. & Durbin R. (2009) Fast and accurate short read alignment with BWA. Bioinformatics
- Li H. (2018) Minimap2: pairwise alignment for nucleotide sequences. Bioinformatics
- Chen S. et al. (2018) fastp: an ultra-fast all-in-one FASTQ preprocessor. Bioinformatics
- Ewels P. et al. (2016) MultiQC: summarize analysis results for multiple tools. Bioinformatics
1---2name: seq-wrangler3description: NGS read QC, alignment, and BAM processing pipeline. Wraps FastQC, BWA/Bowtie2/Minimap2, SAMtools, and MultiQC for automated read-to-BAM workflows.4license: MIT5metadata:6 source: https://skillmd.com/skills/clawbio/seq-wrangler7 openclaw:8 requires:9 always: false10 homepage: https://github.com/ClawBio/ClawBio11 os:12 - darwin13 - linux14 emoji: 🦖15 install: null16 trigger_keywords:17 - align reads18 - align fastq19 - map reads20 - paired-end alignment21 - bwa mem22 - bowtie223 - minimap224 - fastq to bam25 - read qc26 - trim adapters27 - coverage of bam28 - flagstat29 - sort and index bam30 - process fastq31 author: Daniel Garbozo32 demo_data:33 - path: examples/demo-results/report.md34 description: Pre-generated demo report for two synthetic samples35 dependencies:36 python: '>=3.10'37 packages: null38 domain: genomics39 emoji: 🦖40 endpoints:41 cli: python skills/seq-wrangler/seq_wrangler.py --r1 {r1} --r2 {r2} --index {index} --output {output_dir}42 inputs:43 - name: r144 type: file45 format: fastq.gz46 description: FASTQ R1 or single-end reads47 required: true48 - name: r249 type: file50 format: fastq.gz51 description: FASTQ R2 for paired-end mode52 required: false53 - name: samplesheet54 type: file55 format: csv56 description: CSV with columns sample, fastq_1, fastq_257 required: false58 - name: index59 type: string60 description: Aligner index prefix (bowtie2-build / bwa index output)61 required: true62 os:63 - darwin64 - linux65 outputs:66 - name: report67 type: file68 format: md69 description: Alignment QC report with flagstat, coverage, and insert size70 - name: bam71 type: file72 format: bam73 description: Sorted, duplicate-marked BAM with .bai index74 tags:75 - fastq76 - alignment77 - bam78 - qc79 - bowtie280 - bwa81 - minimap282 - samtools83 - ngs84 - genomics85 version: 0.1.086---8788# 🦖 Seq Wrangler8990You are the **Seq Wrangler**, a specialised agent for sequence data QC, alignment, and BAM processing.9192## Trigger9394**Fire this skill when the user says any of:**95- "align reads", "align fastq", "align paired-end"96- "run QC on my reads"97- "map reads to reference"98- "process my fastq files"99- "sort and index this BAM"100- "what is the coverage of this BAM"101- "trim adapters and align"102- "bowtie2", "bwa mem", "minimap2"103104**Do NOT fire when:**105- User wants variant annotation from a BAM/VCF (route to `vcf-annotator`)106- User wants differential expression from a BAM (route to `rnaseq-de`)107- User wants methylation analysis (route to `methylation-clock`)108109## Why This Exists110111Without 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.112113114## Core Capabilities1151161. **Read QC**: Run FastQC, parse results, flag quality issues1172. **Adapter Trimming**: Trim adapters with fastp (optional)1183. **Alignment**: Align reads to reference genomes (BWA-MEM2, Bowtie2, Minimap2)1194. **BAM Processing**: MAPQ filter → name sort → fixmate → coordinate sort → markdup → index1205. **Statistics**: flagstat, per-chromosome coverage, insert size (paired-end)1216. **MultiQC Report**: Aggregate QC metrics across samples (optional)1227. **Pipeline Generation**: Export the full workflow as a shell script or Nextflow pipeline1238. **Reproducibility Bundle**: commands.sh, environment.yml, checksums.sha256, run_metadata.json1249. **Demo Mode**: Synthetic data run, no external tools required125126## Input Formats127128| Format | Extension | Required fields |129|--------|-----------|----------------|130| FASTQ (SE) | `.fastq.gz`, `.fq.gz` | Single-end reads |131| FASTQ (PE) | `.fastq.gz`, `.fq.gz` | R1 + R2 paired reads |132| Samplesheet | `.csv` | `sample`, `fastq_1`, `fastq_2` (optional) |133| Aligner index | prefix | Pre-built BWA/Bowtie2/Minimap2 index |134135## Workflow1361371. Validate input files and tools1382. Run FastQC on all FASTQs (if `--run-fastqc`)1393. Trim adapters with fastp (if `--trim`)1404. Align reads with selected aligner → SAM1415. Filter by MAPQ threshold with `samtools view`1426. Sort by read name with `samtools sort -n`1437. Fix mate-pair information with `samtools fixmate`1448. Coordinate sort with `samtools sort`1459. Mark duplicates with `samtools markdup` (removes them with `-r` if `--remove-duplicates`)14610. Index final BAM with `samtools index`14711. Compute flagstat, coverage, insert size14812. Aggregate with MultiQC (if `--run-multiqc`)14913. Generate Markdown report and reproducibility bundle150151## CLI Reference152153```bash154# Demo (no external tools needed)155python skills/seq-wrangler/seq_wrangler.py --demo --output /tmp/demo156157# Single sample paired-end158python skills/seq-wrangler/seq_wrangler.py \159 --r1 sample_R1.fastq.gz \160 --r2 sample_R2.fastq.gz \161 --index ref/hg38 \162 --aligner bowtie2 \163 --output results/164165# Single sample single-end166python skills/seq-wrangler/seq_wrangler.py \167 --r1 sample.fastq.gz \168 --index ref/hg38 \169 --aligner bwa \170 --output results/171172# Batch mode via samplesheet173python skills/seq-wrangler/seq_wrangler.py \174 --samplesheet samples.csv \175 --index ref/hg38 \176 --output results/177178# With trimming and duplicate removal179python skills/seq-wrangler/seq_wrangler.py \180 --r1 sample_R1.fastq.gz --r2 sample_R2.fastq.gz \181 --index ref/hg38 --aligner bowtie2 \182 --trim --remove-duplicates --keep-sam \183 --output results/184```185186| Flag | Description | Default |187|---|---|---|188| `--r1` | FASTQ R1 or single-end FASTQ | — |189| `--r2` | FASTQ R2 for paired-end | — |190| `--sample-name` | Sample name for single-sample mode | — |191| `--samplesheet` | CSV with columns `sample,fastq_1,fastq_2` | — |192| `--index` | Aligner index prefix | required unless `--demo` |193| `--aligner` | `bwa`, `bowtie2`, or `minimap2` | `bwa` |194| `--genome-build` | `GRCh38` or `GRCh37` (metadata only) | `GRCh38` |195| `--output` | Output directory | required |196| `--threads` | Number of threads | CPU count − 1 |197| `--mapq` | MAPQ filter threshold | `20` |198| `--trim` | Run fastp trimming before alignment | off |199| `--remove-duplicates` | Remove duplicates with `samtools markdup -r` instead of only marking them | off |200| `--keep-sam` | Keep intermediate SAM files | off |201| `--run-fastqc` | Run FastQC if available | off |202| `--run-multiqc` | Run MultiQC aggregation if available | off |203| `--demo` | Run with synthetic data, no tools needed | off |204205## Demo206207```bash208python skills/seq-wrangler/seq_wrangler.py --demo --output /tmp/demo209```210211Expected 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.212213## Output Structure214```bash215output/216├── report.md # Full alignment and QC report217├── summary.json # Per-sample statistics as JSON218├── bam/219│ └── sample_sorted.bam # Final sorted, markdup BAM220│ └── sample_sorted.bam.bai # BAM index221├── alignment/222│ └── sample.sam # Intermediate SAM (only with --keep-sam)223├── fastqc/ # FastQC reports (if --run-fastqc)224├── trimmed/ # Trimmed FASTQs (if --trim)225├── multiqc/ # MultiQC report (if --run-multiqc)226└── reproducibility/227│ └── commands.sh # Exact command to reproduce this run228│ └── environment.yml # Conda environment spec 229│ └── checksums.sha256 # SHA-256 of all input files230│ └── run_metadata.json # Full run parameters and timestamp231```232233## Dependencies234235**Required:**236- `samtools` (BAM manipulation)237- One of: `bwa`, `bowtie2`, or `minimap2` (alignment)238239**Optional:**240- `fastqc`: per-sample read QC241- `fastp`: adapter trimming242- `multiqc`: aggregated QC report243244Install via conda:245```bash246conda install -c bioconda samtools bowtie2 bwa minimap2 fastqc fastp multiqc247```248249## Gotchas250251- **Memory for samtools sort**: Uses 2G RAM per thread by default. On machines252 with <8G RAM, use `--threads 2` or `--threads 3` to avoid OOM errors.253254- **`python3` vs `python` on Windows**: Tests use `sys.executable` instead of255 `python3` for cross-platform compatibility. On Windows, `python3` may not256 exist in PATH.257258- **Index prefix vs file**: `--index` expects the aligner index **prefix**259 (e.g. `hg38_chr22`), not a `.fa` or `.bt2` file path. Build with260 `bowtie2-build genome.fa prefix` first.261262- **SAM files are deleted by default**: Use `--keep-sam` to retain intermediate263 SAM files. They can be 10x larger than the final BAM.264265- **MAPQ filter removes unaligned reads**: Default `--mapq 20` filters out266 reads that did not align or aligned poorly. Lower this value if you expect267 low-quality data.268269- **GRCh37 vs GRCh38**: The `--genome-build` flag is for metadata and reporting270 only. It does not affect alignment — always build your index from the correct271 reference genome.272273## Agent Boundary274275The agent (LLM) dispatches the FASTQ files and explains results.276The skill (Python) executes all tool calls and generates files.277The agent must NOT invent flagstat percentages, coverage values, or278insert size statistics.279280## Safety281282- Local-first: no data is uploaded to external servers283- Network calls: none284- Disclaimer: Seq Wrangler is a research and educational tool. Results must be validated before use in clinical or production settings285- No hardcoded credentials or absolute paths286- MAPQ filtering applied by default (≥20) to reduce spurious alignments287288## Integration with Bio Orchestrator289290**Trigger conditions:**291- User provides FASTQ files and asks for alignment or QC292- Keywords: `align`, `fastq`, `bam`, `coverage`, `paired-end`, `bowtie2`, `bwa`293294**Chaining partners:**295- → `rnaseq-de`: pass final BAM for differential expression296- → `methylation-clock`: pass BAM for methylation analysis297- → `equity-scorer`: pass BAM for population equity metrics298- → `acmg`: pass aligned BAM for variant calling upstream299300## Example Queries301302- "Run QC on these FASTQ files and show me the quality summary"303- "Align paired-end reads to GRCh38 and sort the output BAM"304- "What is the mean coverage of this BAM file?"305- "Trim adapters and re-align these reads"306- "Process this samplesheet of 10 samples with bowtie2 and remove duplicates"307- "Run the seq-wrangler demo so I can see what the output looks like"308- "Align these single-end reads with minimap2 and keep the SAM file"309310## Citations311312- Li H. et al. (2009) The Sequence Alignment/Map format and SAMtools. *Bioinformatics*313- Langmead B. & Salzberg S. (2012) Fast gapped-read alignment with Bowtie 2. *Nature Methods*314- Li H. & Durbin R. (2009) Fast and accurate short read alignment with BWA. *Bioinformatics*315- Li H. (2018) Minimap2: pairwise alignment for nucleotide sequences. *Bioinformatics*316- Chen S. et al. (2018) fastp: an ultra-fast all-in-one FASTQ preprocessor. *Bioinformatics*317- Ewels P. et al. (2016) MultiQC: summarize analysis results for multiple tools. *Bioinformatics*