---
title: Metagenomics quickstart
description: >-
  Step-by-step workflows for taxonomic classification, community profiling,
  diversity analysis, and differential abundance testing.
tags:
  - metagenomics
  - quickstart
---

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

### Step 1: Upload and classify

Ask Ivy in chat (or submit the job directly with `POST /api/v1/jobs`; see the [API reference](/docs/api)):

```
Classify my gut metagenome sample using Kraken2
```

Upload your FASTQ file(s) when prompted, or reference a previously uploaded file. Ivy runs metagenomic classification with Kraken2 as the classifier.

### Step 2: 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 |

### Step 3: Switch to MetaPhlAn for species-level accuracy (optional)

```
Now run MetaPhlAn on the same sample for species-level profiling
```

MetaPhlAn uses clade-specific marker genes and typically reports fewer but more confident species-level assignments.

## Workflow 2: Generate a community profile

### Step 1: Create an abundance profile

```
Generate a genus-level abundance profile from my metagenome samples
```

Or configure manually:

| Parameter | Value |
|-----------|-------|
| Method | `metaphlan` (default) |
| Resolution | `genus` |

### Step 2: 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 |

### Step 3: 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

### Step 1: Compute alpha diversity

```
Calculate Shannon diversity for my microbiome samples
```

Or configure manually:

| Parameter | Value |
|-----------|-------|
| Abundance table URI | from the profiling step |
| Metadata file URI | CSV with `sample`, `group` columns |
| Metrics | `both` (default) |

### Step 2: 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 |

### Step 3: Review beta diversity (optional)

```
Compare community composition between all samples using Bray-Curtis dissimilarity
```

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

### Step 1: Define groups and run analysis

```
Which taxa are differentially abundant between healthy and diseased groups?
```

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) |

### Step 2: 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.

### Step 3: 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](/docs/metagenomics/inputs) for all parameters, database options, and method configurations
- See [outputs](/docs/metagenomics/outputs) for result field descriptions and metric interpretation
- Use [Genomics](/docs/genomics) to look up functional annotations of identified species
- Use [Literature](/docs/pubmed) to search for microbiome-disease association studies

## Read next