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
- Takes paired-end FASTQ files (R1, R2) or a single concatenated FASTQ as input
- Runs Kraken2 taxonomic classification against a standard database (e.g., Standard-8, PlusPF)
- Refines abundances with Bracken at species level (read re-estimation)
- Detects antimicrobial resistance genes with RGI against the CARD database
- Classifies detected ARGs by WHO critical priority pathogen association
- Optionally runs HUMAnN3 for functional pathway profiling (MetaCyc + UniRef)
- 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
- 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)
- 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_profiler.py \
--r1 sample_R1.fastq.gz \
--r2 sample_R2.fastq.gz \
--output metagenomics_report
# Skip HUMAnN3 (faster — taxonomy + resistome only)
python metagenomics_profiler.py \
--r1 sample_R1.fastq.gz \
--r2 sample_R2.fastq.gz \
--output metagenomics_report \
--skip-functional
# Single concatenated FASTQ
python metagenomics_profiler.py \
--input combined.fastq.gz \
--output metagenomics_report
# Specify Kraken2 database path
python metagenomics_profiler.py \
--r1 sample_R1.fastq.gz \
--r2 sample_R2.fastq.gz \
--output metagenomics_report \
--kraken2-db /path/to/kraken2_db \
--read-length 150
Demo (works out of the box)
python metagenomics_profiler.py --demo --output demo_report
The demo uses pre-computed results from the Peru sewage metagenomics study (6 samples, 3 sites) and generates all figures and reports instantly without requiring external tools.
Example Output
Metagenomics Profiler — ClawBio
================================
Mode: demo (pre-computed Peru sewage data)
Samples: 6 (3 sites: Lima, Cusco, Iquitos)
Taxonomy (Kraken2 + Bracken):
Total classified: 94.2%
Top species: Escherichia coli (12.3%), Klebsiella pneumoniae (8.7%),
Pseudomonas aeruginosa (5.1%), Acinetobacter baumannii (3.9%)
Alpha Diversity:
Shannon index: 2.847
Simpson index: 0.912
Pielou evenness: 0.734
Species richness: 48
Resistome (RGI/CARD):
Total ARG hits: 247 (Perfect: 89, Strict: 158)
Drug classes: 14
WHO-Critical ARGs detected: 23
- Carbapenem resistance: NDM-1, OXA-48, KPC-3
- 3rd-gen cephalosporin resistance: CTX-M-15, CTX-M-27
Functional Pathways (HUMAnN3):
Total pathways: 312
Top: PWY-7219 (adenosine ribonucleotides de novo biosynthesis)
Figures saved to: demo_report/figures/
taxonomy_barplot.png (300 dpi)
resistome_heatmap.png (300 dpi)
who_critical_args.png (300 dpi)
Reproducibility:
commands.sh | environment.yml | checksums.sha256
Pipeline Architecture
FASTQ R1 + R2
|
v
[Kraken2] --> kraken2_report.txt
|
v
[Bracken] --> bracken_species.tsv --> Figure 1: Taxonomy bar chart
|
v
[RGI MAIN] --> rgi_results.txt --> Figure 2: Resistome heatmap
| --> Figure 3: WHO-critical ARG summary
v
[HUMAnN3] --> pathabundance.tsv (optional, --skip-functional to omit)
|
v
[Report] --> report.md + figures/ + reproducibility/
Database Requirements
| Tool |
Database |
Size |
Notes |
| Kraken2 |
Standard-8 or PlusPF |
8-70 GB |
Set via --kraken2-db or $KRAKEN2_DB |
| Bracken |
(built from Kraken2 DB) |
included |
Read-length specific (default: 150 bp) |
| RGI |
CARD |
~500 MB |
Auto-downloaded via rgi auto_load |
| HUMAnN3 |
ChocoPhlAn + UniRef90 |
~15 GB |
Set via --humann-db or $HUMANN_DB |
Citations
If you use this skill in a publication, please cite:
- Wood, D.E., Lu, J. & Langmead, B. (2019). Improved metagenomic analysis with Kraken 2. Genome Biology, 20, 257.
- Lu, J. et al. (2017). Bracken: estimating species abundance in metagenomics data. PeerJ Computer Science, 3, e104.
- Alcock, B.P. et al. (2023). CARD 2023: expanded curation, support for machine learning, and resistome prediction at the Comprehensive Antibiotic Resistance Database. Nucleic Acids Research, 51(D1), D419-D430.
- Beghini, F. et al. (2021). Integrating taxonomic, functional, and strain-level profiling of diverse microbial communities with bioBakery 3. eLife, 10, e65088.
- Corpas, M. (2026). ClawBio. https://github.com/ClawBio/ClawBio
1---
2name: claw-metagenomics
3description: Shotgun metagenomics profiling — taxonomy, resistome, and functional pathways
4license: MIT
5metadata:
6 source: https://skillmd.com/skills/clawbio/claw-metagenomics
7 version: 0.1.0
8 author: Manuel Corpas
9 tags:
10 - metagenomics
11 - antimicrobial-resistance
12 - taxonomy
13 - functional-profiling
14 - environmental
15 - WHO-critical-ARGs
16 inputs:
17 - name: r1
18 type: file
19 format:
20 - fastq
21 - fastq.gz
22 - fq
23 - fq.gz
24 description: Forward reads (paired-end FASTQ R1)
25 - name: r2
26 type: file
27 format:
28 - fastq
29 - fastq.gz
30 - fq
31 - fq.gz
32 description: Reverse reads (paired-end FASTQ R2)
33 - name: input
34 type: file
35 format:
36 - fastq
37 - fastq.gz
38 - fq
39 - fq.gz
40 description: Single concatenated or interleaved FASTQ (alternative to R1+R2)
41 outputs:
42 - name: taxonomy_report
43 type: file
44 format: tsv
45 description: Bracken-adjusted species-level taxonomy abundance table
46 - name: resistome_profile
47 type: file
48 format: tsv
49 description: RGI/CARD antimicrobial resistance gene hits with WHO priority classification
50 - name: functional_pathways
51 type: file
52 format: tsv
53 description: HUMAnN3 pathway abundance table (MetaCyc/UniRef)
54 - name: figures
55 type: directory
56 format:
57 - png
58 - pdf
59 description: Publication-quality figures (taxonomy bar chart, resistome heatmap, WHO-critical ARG summary)
60 - name: reproducibility
61 type: directory
62 description: commands.sh, environment.yml, checksums.sha256
63 openclaw:
64 category: bioinformatics
65 emoji: 🦠
66 homepage: https://github.com/ClawBio/ClawBio
67 os:
68 - darwin
69 - linux
70 min_python: '3.9'
71 dependencies:
72 - pandas
73 - numpy
74 - matplotlib
75 - seaborn
76 - scipy
77 - biopython
78 system_dependencies:
79 - kraken2
80 - bracken
81 - rgi
82 - humann
83 requires:
84 bins:
85 - python3
86 always: false
87---
88
89# Shotgun Metagenomics Profiler
90
91Comprehensive shotgun metagenomics analysis combining taxonomic classification, antimicrobial resistance gene detection, and functional pathway profiling from paired-end FASTQ files.
92
93## What it does
94
951. Takes paired-end FASTQ files (R1, R2) or a single concatenated FASTQ as input
962. Runs **Kraken2** taxonomic classification against a standard database (e.g., Standard-8, PlusPF)
973. Refines abundances with **Bracken** at species level (read re-estimation)
984. Detects antimicrobial resistance genes with **RGI** against the **CARD** database
995. Classifies detected ARGs by **WHO critical priority pathogen** association
1006. Optionally runs **HUMAnN3** for functional pathway profiling (MetaCyc + UniRef)
1017. Calculates **alpha diversity metrics** from Bracken-adjusted species abundances:
102 - **Shannon diversity index**: H = -sum(p_i * ln(p_i)), where p_i is the proportion of classified reads assigned to species i
103 - **Simpson diversity index**: D = 1 - sum(p_i^2)
104 - **Pielou evenness**: J = H / ln(S), where S is the number of species detected
105 - **Species richness**: S = number of distinct species with at least 1 assigned read
1068. Generates four publication-quality figures:
107 - **Figure 1**: Taxonomy bar chart, top 20 species by relative abundance
108 - **Figure 2**: Resistome heatmap, ARG families by drug class with abundance
109 - **Figure 3**: WHO-critical ARG summary, priority-tier breakdown of detected resistance genes
110 - **Figure 4**: Alpha diversity summary (Shannon, Simpson, Pielou in a panel)
1119. Produces a full reproducibility bundle (commands.sh, environment.yml, checksums.sha256)
112
113## Why this exists
114
115If you ask a general AI to "analyse a metagenome," it will:
116- Not know which Kraken2 database to use or how to set confidence thresholds
117- Hallucinate Bracken parameters for read-length and taxonomic level
118- Miss the connection between detected ARGs and WHO priority pathogen lists
119- Skip HUMAnN3 entirely (or misconfigure its database paths)
120- Produce a single bar chart with no resistance context
121- Skip diversity metric calculations (Shannon, Simpson, Pielou)
122- Not provide a reproducibility bundle
123
124This skill encodes the correct methodological decisions:
125- Kraken2 confidence threshold of 0.2 (reduces false positives in environmental samples)
126- Bracken re-estimation at species level with minimum 10 reads
127- RGI MAIN with "Perfect" and "Strict" hit criteria only (no "Loose" hits)
128- WHO Critical Priority Pathogen list mapped to detected ARG families
129- HUMAnN3 with MetaCyc stratification for pathway-level functional context
130- Thread count auto-detected from available CPUs
131- Full reproducibility bundle for every run
132
133## Validated On
134
135The skill works with any shotgun metagenome but has been validated on:
136- **Peru sewage metagenomics study** (6 samples, 3 collection sites: Lima, Cusco, Iquitos)
137- Environmental sewage samples with mixed microbial communities
138- Read depths ranging from 2M to 15M paired-end reads per sample
139
140## WHO-Critical ARG Detection
141
142A key feature is the classification of detected resistance genes by WHO priority tier:
143
144| Priority | Pathogen | Resistance |
145|----------|----------|------------|
146| Critical | *Acinetobacter baumannii* | Carbapenem-resistant |
147| Critical | *Pseudomonas aeruginosa* | Carbapenem-resistant |
148| Critical | *Enterobacteriaceae* | Carbapenem-resistant, 3rd-gen cephalosporin-resistant |
149| High | *Enterococcus faecium* | Vancomycin-resistant |
150| High | *Staphylococcus aureus* | Methicillin-resistant, vancomycin-resistant |
151| High | *Helicobacter pylori* | Clarithromycin-resistant |
152| High | *Campylobacter* | Fluoroquinolone-resistant |
153| High | *Salmonella* spp. | Fluoroquinolone-resistant |
154| High | *Neisseria gonorrhoeae* | 3rd-gen cephalosporin-resistant, fluoroquinolone-resistant |
155| Medium | *Streptococcus pneumoniae* | Penicillin-non-susceptible |
156| Medium | *Haemophilus influenzae* | Ampicillin-resistant |
157| Medium | *Shigella* spp. | Fluoroquinolone-resistant |
158
159## Usage
160
161```bash
162# Full pipeline (taxonomy + resistome + functional)
163python metagenomics_profiler.py \
164 --r1 sample_R1.fastq.gz \
165 --r2 sample_R2.fastq.gz \
166 --output metagenomics_report
167
168# Skip HUMAnN3 (faster — taxonomy + resistome only)
169python metagenomics_profiler.py \
170 --r1 sample_R1.fastq.gz \
171 --r2 sample_R2.fastq.gz \
172 --output metagenomics_report \
173 --skip-functional
174
175# Single concatenated FASTQ
176python metagenomics_profiler.py \
177 --input combined.fastq.gz \
178 --output metagenomics_report
179
180# Specify Kraken2 database path
181python metagenomics_profiler.py \
182 --r1 sample_R1.fastq.gz \
183 --r2 sample_R2.fastq.gz \
184 --output metagenomics_report \
185 --kraken2-db /path/to/kraken2_db \
186 --read-length 150
187```
188
189### Demo (works out of the box)
190
191```bash
192python metagenomics_profiler.py --demo --output demo_report
193```
194
195The demo uses pre-computed results from the Peru sewage metagenomics study (6 samples, 3 sites) and generates all figures and reports instantly without requiring external tools.
196
197## Example Output
198
199```
200Metagenomics Profiler — ClawBio
201================================
202Mode: demo (pre-computed Peru sewage data)
203Samples: 6 (3 sites: Lima, Cusco, Iquitos)
204
205Taxonomy (Kraken2 + Bracken):
206 Total classified: 94.2%
207 Top species: Escherichia coli (12.3%), Klebsiella pneumoniae (8.7%),
208 Pseudomonas aeruginosa (5.1%), Acinetobacter baumannii (3.9%)
209
210Alpha Diversity:
211 Shannon index: 2.847
212 Simpson index: 0.912
213 Pielou evenness: 0.734
214 Species richness: 48
215
216Resistome (RGI/CARD):
217 Total ARG hits: 247 (Perfect: 89, Strict: 158)
218 Drug classes: 14
219 WHO-Critical ARGs detected: 23
220 - Carbapenem resistance: NDM-1, OXA-48, KPC-3
221 - 3rd-gen cephalosporin resistance: CTX-M-15, CTX-M-27
222
223Functional Pathways (HUMAnN3):
224 Total pathways: 312
225 Top: PWY-7219 (adenosine ribonucleotides de novo biosynthesis)
226
227Figures saved to: demo_report/figures/
228 taxonomy_barplot.png (300 dpi)
229 resistome_heatmap.png (300 dpi)
230 who_critical_args.png (300 dpi)
231
232Reproducibility:
233 commands.sh | environment.yml | checksums.sha256
234```
235
236## Pipeline Architecture
237
238```
239FASTQ R1 + R2
240 |
241 v
242[Kraken2] --> kraken2_report.txt
243 |
244 v
245[Bracken] --> bracken_species.tsv --> Figure 1: Taxonomy bar chart
246 |
247 v
248[RGI MAIN] --> rgi_results.txt --> Figure 2: Resistome heatmap
249 | --> Figure 3: WHO-critical ARG summary
250 v
251[HUMAnN3] --> pathabundance.tsv (optional, --skip-functional to omit)
252 |
253 v
254[Report] --> report.md + figures/ + reproducibility/
255```
256
257## Database Requirements
258
259| Tool | Database | Size | Notes |
260|------|----------|------|-------|
261| Kraken2 | Standard-8 or PlusPF | 8-70 GB | Set via `--kraken2-db` or `$KRAKEN2_DB` |
262| Bracken | (built from Kraken2 DB) | included | Read-length specific (default: 150 bp) |
263| RGI | CARD | ~500 MB | Auto-downloaded via `rgi auto_load` |
264| HUMAnN3 | ChocoPhlAn + UniRef90 | ~15 GB | Set via `--humann-db` or `$HUMANN_DB` |
265
266## Citations
267
268If you use this skill in a publication, please cite:
269
270- Wood, D.E., Lu, J. & Langmead, B. (2019). Improved metagenomic analysis with Kraken 2. Genome Biology, 20, 257.
271- Lu, J. et al. (2017). Bracken: estimating species abundance in metagenomics data. PeerJ Computer Science, 3, e104.
272- Alcock, B.P. et al. (2023). CARD 2023: expanded curation, support for machine learning, and resistome prediction at the Comprehensive Antibiotic Resistance Database. Nucleic Acids Research, 51(D1), D419-D430.
273- Beghini, F. et al. (2021). Integrating taxonomic, functional, and strain-level profiling of diverse microbial communities with bioBakery 3. eLife, 10, e65088.
274- Corpas, M. (2026). ClawBio. https://github.com/ClawBio/ClawBio