Metagenomics quickstart
Step-by-step workflows for taxonomic classification, community profiling, diversity analysis, and differential abundance testing.
You want to know which organisms are in your samples and how their communities differ; this walks you through four common workflows — classifying metagenome reads, generating community profiles, calculating diversity metrics, and identifying differentially abundant taxa — from raw FASTQ through statistical comparison.
Metagenomics quickstart
This guide covers four common workflows: classifying metagenome reads, generating community profiles, calculating diversity metrics, and identifying differentially abundant taxa.
Workflow 1: Classify metagenome reads
Upload and classify
Ask Ivy in chat (or submit the job directly with POST /api/v1/jobs; see the API reference):
Upload your FASTQ file(s) when prompted, or reference a previously uploaded file. Ivy runs metagenomic classification with Kraken2 as the classifier.
Review classification results
| Field | Example Value |
|---|---|
| Total reads | 1,250,000 |
| Classified reads | 1,087,500 |
| Classification rate | 0.87 |
Top taxon (taxa[0]) | Bacteroides fragilis, abundance 0.18 |
Switch to MetaPhlAn for species-level accuracy (optional)
MetaPhlAn uses clade-specific marker genes and typically reports fewer but more confident species-level assignments.
Workflow 2: Generate a community profile
Create an abundance profile
Or configure manually:
| Parameter | Value |
|---|---|
| Method | metaphlan (default) |
| Resolution | genus |
Review the community profile
metagenomics_profile returns one summary per sample, not a multi-sample abundance matrix:
| Field | Example Value |
|---|---|
| Richness | 187 taxa |
| Evenness | 0.74 |
| Dominant taxon | Bacteroides |
| Dominant abundance | 0.31 |
Top phylum (phylum_abundances) | Firmicutes: 0.45, Bacteroidetes: 0.38 |
Repeat for each sample
Run metagenomics_profile once per sample, then pass the resulting profiles into microbiome_diversity or microbiome_differential to compare across samples.
Workflow 3: Calculate diversity metrics
Compute alpha diversity
Or configure manually:
| Parameter | Value |
|---|---|
| Abundance table URI | from the profiling step |
| Metadata file URI | CSV with sample, group columns |
| Metrics | both (default) |
Review alpha diversity results
| Sample | Shannon | Simpson | Chao1 | Observed species |
|---|---|---|---|---|
| Sample_1 | 3.42 | 0.91 | 201 | 187 |
| Sample_2 | 3.28 | 0.89 | 184 | 172 |
| Sample_3 | 2.95 | 0.85 | 169 | 156 |
Review beta diversity (optional)
Set beta_method: "bray_curtis" (the default). This returns a Bray-Curtis distance to every other sample under each sample's beta_distances field — there's no ordination (PCoA/NMDS) output.
| Sample_1 | Sample_2 | Sample_3 | |
|---|---|---|---|
| Sample_1 | 0.000 | 0.213 | 0.387 |
| Sample_2 | 0.213 | 0.000 | 0.298 |
| Sample_3 | 0.387 | 0.298 | 0.000 |
Workflow 4: Differential abundance analysis
Define groups and run analysis
Or configure manually:
| Parameter | Value |
|---|---|
| Abundance table URI | Uploaded or generated table |
| Metadata file URI | CSV with sample, condition columns |
| Contrast | "diseased_vs_healthy" |
| Method | ancombc (default) |
Review differentially abundant taxa
significant_taxa is already filtered to adjusted p-value < 0.05:
| Taxon | Log2 Fold Change | Adjusted P-value |
|---|---|---|
| Fusobacterium nucleatum | 3.21 | 0.001 |
| Porphyromonas gingivalis | 2.87 | 0.003 |
| Faecalibacterium prausnitzii | -2.45 | 0.008 |
| Roseburia intestinalis | -1.98 | 0.021 |
A positive log2 fold change means the taxon is enriched in the second half of the contrast (here, diseased); negative means depleted.
Interpret the results
| Log2 Fold Change | Interpretation |
|---|---|
| > 2.0 | Strong enrichment in group 2 (diseased) |
| 1.0 to 2.0 | Moderate enrichment |
| -1.0 to 1.0 | Not biologically significant |
| -2.0 to -1.0 | Moderate depletion |
| < -2.0 | Strong depletion in group 2 |
Next steps
- See inputs for all parameters, database options, and method configurations
- See outputs for result field descriptions and metric interpretation
- Use Genomics to look up functional annotations of identified species
- Use Literature to search for microbiome-disease association studies
Read next
Metagenomics inputs and parameters
FASTQ formats, database selection, diversity metrics, statistical methods, and configuration options for all metagenomics tools.
Metagenomics on the platform
Taxonomic classification, community profiling, diversity analysis, and differential abundance tools for microbiome and metagenomic studies.
Was this page helpful?