/claw-metagenomics

name: claw-metagenomics
description: Shotgun metagenomics profiling — taxonomy, resistome, and functional pathways
license: MIT
metadata:
  version: 0.1.0
  author: Manuel Corpas
  tags:
  - metagenomics
  - antimicrobial-resistance
  - taxonomy
  - functional-profiling
  - environmental
  - WHO-critical-ARGs
  inputs:
  - name: r1
    type: file
    format:
    - fastq
    - fastq.gz
    - fq
    - fq.gz
    description: Forward reads (paired-end FASTQ R1)
  - name: r2
    type: file
    format:
    - fastq
    - fastq.gz
    - fq
    - fq.gz
    description: Reverse reads (paired-end FASTQ R2)
  - name: input
    type: file
    format:
    - fastq
    - fastq.gz
    - fq
    - fq.gz
    description: Single concatenated or interleaved FASTQ (alternative to R1+R2)
  outputs:
  - name: taxonomy_report
    type: file
    format: tsv
    description: Bracken-adjusted species-level taxonomy abundance table
  - name: resistome_profile
    type: file
    format: tsv
    description: RGI/CARD antimicrobial resistance gene hits with WHO priority classification
  - name: functional_pathways
    type: file
    format: tsv
    description: HUMAnN3 pathway abundance table (MetaCyc/UniRef)
  - name: figures
    type: directory
    format:
    - png
    - pdf
    description: Publication-quality figures (taxonomy bar chart, resistome heatmap, WHO-critical ARG summary)
  - name: reproducibility
    type: directory
    description: commands.sh, environment.yml, checksums.sha256
  openclaw:
    category: bioinformatics
    emoji: 🦠
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    min_python: '3.9'
    dependencies:
    - pandas
    - numpy
    - matplotlib
    - seaborn
    - scipy
    - biopython
    system_dependencies:
    - kraken2
    - bracken
    - rgi
    - humann
    requires:
      bins:
      - python3
    always: false

Shotgun Metagenomics Profiler

Comprehensive shotgun metagenomics analysis combining taxonomic classification, antimicrobial resistance gene detection, and functional pathway profiling from paired-end FASTQ files.

What it does

1. Takes paired-end FASTQ files (R1, R2) or a single concatenated FASTQ as input 2. Runs **Kraken2** taxonomic classification against a standard database (e.g., Standard-8, PlusPF) 3. Refines abundances with **Bracken** at species level (read re-estimation) 4. Detects antimicrobial resistance genes with **RGI** against the **CARD** database 5. Classifies detected ARGs by **WHO critical priority pathogen** association 6. Optionally runs **HUMAnN3** for functional pathway profiling (MetaCyc + UniRef) 7. Calculates **alpha diversity metrics** from Bracken-adjusted species abundances:

• **Shannon diversity index**: H = -sum(p_i * ln(p_i)), where p_i is the proportion of classified reads assigned to species i
• **Simpson diversity index**: D = 1 - sum(p_i^2)
• **Pielou evenness**: J = H / ln(S), where S is the number of species detected
• **Species richness**: S = number of distinct species with at least 1 assigned read

8. Generates four publication-quality figures:

• **Figure 1**: Taxonomy bar chart, top 20 species by relative abundance
• **Figure 2**: Resistome heatmap, ARG families by drug class with abundance
• **Figure 3**: WHO-critical ARG summary, priority-tier breakdown of detected resistance genes
• **Figure 4**: Alpha diversity summary (Shannon, Simpson, Pielou in a panel)

9. Produces a full reproducibility bundle (commands.sh, environment.yml, checksums.sha256)

Why this exists

If you ask a general AI to "analyse a metagenome," it will:

• Not know which Kraken2 database to use or how to set confidence thresholds
• Hallucinate Bracken parameters for read-length and taxonomic level
• Miss the connection between detected ARGs and WHO priority pathogen lists
• Skip HUMAnN3 entirely (or misconfigure its database paths)
• Produce a single bar chart with no resistance context
• Skip diversity metric calculations (Shannon, Simpson, Pielou)
• Not provide a reproducibility bundle

This skill encodes the correct methodological decisions:

• Kraken2 confidence threshold of 0.2 (reduces false positives in environmental samples)
• Bracken re-estimation at species level with minimum 10 reads
• RGI MAIN with "Perfect" and "Strict" hit criteria only (no "Loose" hits)
• WHO Critical Priority Pathogen list mapped to detected ARG families
• HUMAnN3 with MetaCyc stratification for pathway-level functional context
• Thread count auto-detected from available CPUs
• Full reproducibility bundle for every run

Validated On

The skill works with any shotgun metagenome but has been validated on:

• **Peru sewage metagenomics study** (6 samples, 3 collection sites: Lima, Cusco, Iquitos)
• Environmental sewage samples with mixed microbial communities
• Read depths ranging from 2M to 15M paired-end reads per sample

WHO-Critical ARG Detection

A key feature is the classification of detected resistance genes by WHO priority tier:

| Priority | Pathogen | Resistance | |----------|----------|------------| | Critical | *Acinetobacter baumannii* | Carbapenem-resistant | | Critical | *Pseudomonas aeruginosa* | Carbapenem-resistant | | Critical | *Enterobacteriaceae* | Carbapenem-resistant, 3rd-gen cephalosporin-resistant | | High | *Enterococcus faecium* | Vancomycin-resistant | | High | *Staphylococcus aureus* | Methicillin-resistant, vancomycin-resistant | | High | *Helicobacter pylori* | Clarithromycin-resistant | | High | *Campylobacter* | Fluoroquinolone-resistant | | High | *Salmonella* spp. | Fluoroquinolone-resistant | | High | *Neisseria gonorrhoeae* | 3rd-gen cephalosporin-resistant, fluoroquinolone-resistant | | Medium | *Streptococcus pneumoniae* | Penicillin-non-susceptible | | Medium | *Haemophilus influenzae* | Ampicillin-resistant | | Medium | *Shigella* spp. | Fluoroquinolone-resistant |

Usage

# Full pipeline (taxonomy + resistome + functional)
python metagenomics_profile