---
title: Metagenomics on the platform
description: >-
  Taxonomic classification, community profiling, diversity analysis, and
  differential abundance tools for microbiome and metagenomic studies.
tags:
  - metagenomics
---

Metagenomics tells you which organisms are present in a sample and how their communities differ between conditions — running the full microbiome pipeline from raw-read taxonomic classification through diversity and differential-abundance statistics. Reach for it when your biology lives in a microbial community rather than a single genome, such as profiling a stool sample or comparing treatment versus control microbiomes. Where [genomics](/docs/genomics) queries curated databases for a known gene, metagenomics classifies unknown sequencing reads and can hand abundant species back to genomics for functional annotation. See [what you can achieve](/docs/capabilities#genomics-and-omics) for the full set.

## Metagenomics overview

The Metagenomics toolkit provides a complete pipeline for microbiome analysis, from raw read classification through statistical comparison of community composition. All tools run as GPU-accelerated Modal jobs. Classification and profiling typically take 5-45 minutes depending on read count; downstream diversity and differential abundance analysis take 3-20 minutes.

## Architecture

```
User Input (FASTQ reads, abundance table, sample metadata)
  --> Intent Detection
       |- Taxonomic classification --> metagenomics_classify
       |- Community profiling --> metagenomics_profile
       |- Diversity analysis --> microbiome_diversity
       +- Differential abundance --> microbiome_differential
  --> Modal GPU Compute (classification) or Direct Compute (stats)
  --> Structured Results with Abundance Tables and Statistics
```

## Tool inventory

| Tool | Name | Description | Compute |
|------|------|-------------|---------|
| Metagenomics Classify | `metagenomics_classify` | Taxonomic read classification using Kraken2, Centrifuge, or Kaiju | Modal GPU |
| Metagenomics Profile | `metagenomics_profile` | Community abundance profiling at configurable taxonomic ranks | Modal GPU |
| Microbiome Diversity | `microbiome_diversity` | Alpha and beta diversity metric calculation | Modal GPU |
| Microbiome Differential | `microbiome_differential` | Differential abundance testing between sample groups | Modal GPU |

## Capabilities

### Taxonomic classification

`metagenomics_classify` assigns taxonomic labels to individual reads (`method`: `kraken2`, `centrifuge`, or `kaiju`, against a `standard`, `silva`, or `greengenes` database). `metagenomics_profile` instead produces a quantitative, per-sample community summary (`method`: `metaphlan`, `bracken`, or `motu`) — read-level classification and quantitative profiling are two separate tools, not two modes of one tool.

| Tool | Method options | Speed | Best For |
|--------|-----------|-------|----------|
| `metagenomics_classify` | `kraken2` (default), `centrifuge`, `kaiju` | Fast, exact k-mer/index matching | Broad read-level classification, large datasets |
| `metagenomics_profile` | `metaphlan` (default), `bracken`, `motu` | Moderate, marker/re-estimation based | Quantitative community composition, low false-positive rates |

### Community profiling

The `metagenomics_profile` tool generates a per-sample community summary (richness, evenness, dominant taxon, and phylum-level abundances) at a configurable taxonomic resolution (species, genus, or family). Run it once per sample, then pass the results into `microbiome_diversity` or `microbiome_differential` to compare across samples.

### Alpha diversity

Alpha diversity quantifies the species diversity within individual samples. `microbiome_diversity` always returns these four metrics per sample:

| Metric | What It Measures | Range | Interpretation |
|--------|-----------------|-------|----------------|
| Shannon index (H') | Richness + evenness | 0 to ~5 | Higher = more diverse |
| Simpson index (1-D) | Dominance-weighted diversity | 0 to 1 | Higher = more diverse |
| Observed species | Raw species count | 0 to N | Higher = more species |
| Chao1 | Estimated true richness | ≥ observed | Accounts for unseen species |

### Beta diversity

Beta diversity measures compositional differences between samples, returned as a distance to every other sample (`beta_distances`). `beta_method` selects the distance:

| Metric | Algorithm | Best For |
|--------|-----------|----------|
| Bray-Curtis (default) | Abundance-weighted dissimilarity | General community comparison |
| Jaccard | Presence/absence dissimilarity | Binary composition comparison |
| UniFrac | Phylogeny-weighted dissimilarity | Evolutionary composition |

There's no ordination (PCoA/NMDS) step — `beta_distances` is a distance map, not a set of plotting coordinates.

### Differential abundance

The `microbiome_differential` tool identifies taxa with significantly different abundances between experimental groups, all methods designed for compositional microbiome data:

| Method | Algorithm | Best For |
|--------|-----------|----------|
| ANCOM-BC (default) | Bias-corrected log-linear model | Controlling for variable sampling fraction |
| ALDEx2 | Bayesian CLR + Welch's t-test | Compositional-aware analysis |
| MaAsLin2 | Generalized linear models | Multivariate association testing |

## When to use each tool

| I want to... | Use this tool |
|--------------|---------------|
| Identify what organisms are in my sample | `metagenomics_classify` |
| Get species-level abundance table | `metagenomics_profile` |
| Compare species richness across samples | `microbiome_diversity` (alpha) |
| Compare community composition between groups | `microbiome_diversity` (beta) |
| Find taxa enriched in disease vs healthy | `microbiome_differential` |
| Generate a stacked bar chart of community composition | `metagenomics_profile` |

## When to use other tools instead

| I want to... | Use this instead |
|--------------|------------------|
| Assemble metagenome contigs | External assembler (megahit, SPAdes) |
| Annotate functional genes in metagenomes | A KEGG pathway search ([Genomics](/docs/genomics)) for pathway context |
| Search for a specific gene in sequences | [BLAST](/docs/blast) |
| Model community metabolism | Flux balance analysis ([Systems Biology](/docs/systems-biology)) with community models |
| Find microbiome-related literature | [PubMed](/docs/pubmed) |
| Look up pathogen gene information | An NCBI Entrez search ([Genomics](/docs/genomics)) |

## Licensing

| Component | License |
|-----------|---------|
| Kraken2 | MIT |
| MetaPhlAn | MIT |
| ANCOM-BC | Artistic-2.0 |
| ALDEx2 | GPL (>= 3) |
| MaAsLin2 | MIT |

## Citations

> Wood DE, Lu J, Langmead B. Improved metagenomic analysis with Kraken 2. *Genome Biol*. 2019;20:257. doi: [10.1186/s13059-019-1891-0](https://doi.org/10.1186/s13059-019-1891-0)

> Blanco-Miguez A, et al. Extending and improving metagenomic taxonomic profiling with uncharacterized species using MetaPhlAn 4. *Nat Biotechnol*. 2023;41:1633-1644. doi: [10.1038/s41587-023-01688-w](https://doi.org/10.1038/s41587-023-01688-w)

> Lin H, Peddada SD. Analysis of compositions of microbiomes with bias correction. *Nat Commun*. 2020;11:3514. doi: [10.1038/s41467-020-17041-7](https://doi.org/10.1038/s41467-020-17041-7)

## Chat Usage

### Example Prompts

- "Classify my stool metagenome FASTQ reads with Kraken2"
- "Generate a genus-level abundance profile from my samples"
- "Calculate Shannon and Simpson diversity for all my samples"
- "What taxa are enriched in the treatment group vs control?"
- "Compare community beta diversity using Bray-Curtis PCoA"
- "Run MetaPhlAn species-level profiling on my paired-end reads"

### Workflow Chaining

- **Feeds into**: Literature search (microbiome-disease associations), Systems Biology (community metabolic modeling), Genomics (functional gene annotation of abundant species), Target Passport (pathogen-derived targets)
- **Accepts from**: Data upload (FASTQ files, abundance tables), Literature search (study design metadata), Genomics (reference genome annotations)

## FAQ

### What sequencing data formats are supported?

  The classification and profiling tools accept FASTQ files (single-end or paired-end). Diversity and differential-abundance analysis take the abundance-table output of `metagenomics_profile` plus a sample metadata file, rather than an independently uploaded FASTA or OTU/ASV table.

### What is the difference between Kraken2 and MetaPhlAn?

  Kraken2 uses exact k-mer matching against a reference database for fast taxonomic classification. MetaPhlAn uses clade-specific marker genes for species-level profiling with lower false-positive rates. Use Kraken2 for speed and broad classification; use MetaPhlAn for accurate species-level abundance estimation.

### Can I analyze 16S amplicon data?

  Yes. The metagenomics_classify tool supports both whole-genome shotgun (WGS) and 16S amplicon sequencing data. For 16S data, select the appropriate reference database (e.g., Silva or Greengenes). Diversity and differential abundance tools work with any abundance table regardless of sequencing method.

### How are alpha and beta diversity different?

  Alpha diversity measures species diversity within a single sample (richness, evenness, or both). Beta diversity measures compositional differences between samples (how different two communities are). Common alpha metrics include Shannon index and Simpson index. Common beta metrics include Bray-Curtis dissimilarity and UniFrac distance.

## Read next