alterlab-ieu/alterlab-academic-skills/alterlab-qiime2-amplicon

QIIME 2 Amplicon — 16S/ITS Microbiome Pipeline (FASTQ → Feature Table → Taxonomy → Diversity)

The command-line, workflow-runner entry point for marker-gene (amplicon) microbiome analysis. Given raw demultiplexed paired-end reads, it walks the canonical QIIME 2 order — import → primer trim → denoise → classify → diversity — and teaches the two things people get wrong most: trimming primers BEFORE DADA2, and the .qza/.qzv provenance model. It is the raw-data-to-result pipeline that hands a feature table off to in-memory analysis skills (see routing below).

Written against QIIME 2 2026.7 (released 2026-07-22), the current release. The distribution formerly called amplicon was renamed `qiime2` in 2026.4, and its conda env files carry a rachis- prefix (the framework package was renamed qiime2 -> rachis in 2026.1). Only the env name, channel path, and file names moved: every plugin command below is unchanged across those releases.

When to Use This Skill

Use this skill when the request involves running an amplicon / microbiome pipeline from sequencing reads:

• "Run a QIIME 2 16S pipeline on my paired-end reads."
• "I have ITS amplicon FASTQs — denoise with DADA2 and assign taxonomy."
• "Build a feature table / ASV table and classify against SILVA."
• "Pick truncation lengths from my quality plot and run core-metrics diversity."
• "How do I trim primers before DADA2 in QIIME 2?"
• "What's the right order of QIIME 2 commands?"

Does NOT Trigger — route these elsewhere

This skill is amplicon (marker-gene) only. If the data is shotgun metagenomic, single-cell, or anything other than 16S/18S/ITS marker-gene sequencing, say so and stop.

The Artifact Model (.qza / .qzv) — read this first

Everything in QIIME 2 is a typed, zipped artifact that records its own provenance:

• `.qza` — a QIIME 2 Artifact: data (a feature table, sequences, a classifier)

plus an embedded semantic type (e.g. SampleData[PairedEndSequencesWithQuality], FeatureTable[Frequency]) and a full provenance graph of every action that produced it.

• `.qzv` — a Visualization: a human-viewable report (quality plots, summaries,

diversity emperor plots). Drag it into https://view.qiime2.org (offline, in-browser) or run qiime tools view file.qzv.

• Provenance is the reproducibility win: any .qza/.qzv carries the exact commands,

parameters, and plugin versions that made it. Keep artifacts, not just exports.

Treat semantic types as the contract: an action only accepts artifacts of the type it declares, which is why import (step 1) matters so much.

The Canonical Order (do not reorder)

manifest import → cutadapt trim-paired (primers) → dada2 denoise-paired
   → feature-table summarize → feature-classifier classify-sklearn
   → phylogeny → diversity core-metrics-phylogenetic

Primer trimming comes BEFORE DADA2. DADA2 models per-base error rates; leftover primer/adapter bases corrupt that error model and inflate spurious ASVs. Trim with cutadapt trim-paired first, then denoise. (If your reads are already primer-free — e.g. EMP-style — you can skip cutadapt, but verify, don't assume.)

0. Install / activate the environment (conda only — no pip)

QIIME 2 cannot be pip-installed; it ships as a conda environment. For 2026.7 (env files verified in qiime2/distributions):

# Linux — 2026.7 qiime2 distribution
conda env create \
  --name rachis-qiime2-2026.7 \
  --file https://raw.githubusercontent.com/qiime2/distributions/refs/heads/dev/2026.7/qiime2/released/rachis-qiime2-linux-64-conda.yml
# macOS: swap the filename for rachis-qiime2-osx-64-conda.yml
conda activate rachis-qiime2-2026.7
qiime info   # confirm version + installed plugins

The env file names encode the platform (linux-64, osx-64), not the OS-runner names used before 2026.4. Give each release its own environment — the classifier must match the running version, so parallel envs are the norm, not clutter.

For other releases the same pattern applies with the version swapped in both the env name and the URL path; see the QIIME 2 Library quickstart. Full install detail and the env-file matrix: `references/installation.md`.

Bulk DADA2 denoising and classifier training are CPU/RAM heavy. On Cem's M4 Max these

run fine locally — keep them off the API and run them in a conda activated shell.

1. Import demultiplexed paired-end reads (manifest)

Use a manifest (a TSV mapping sample IDs → absolute FASTQ paths) so you control exactly which files map to which sample. Format: PairedEndFastqManifestPhred33V2 (verified in q2-types).

qiime tools import \
  --type 'SampleData[PairedEndSequencesWithQuality]' \
  --input-format PairedEndFastqManifestPhred33V2 \
  --input-path manifest.tsv \
  --output-path demux.qza
 
qiime demux summarize \
  --i-data demux.qza \
  --o-visualization demux.qzv     # ← READ THIS to choose trunc-len

Manifest schema, single-end and EMP variants, and ITS notes: `references/import_and_manifest.md`. Generate a manifest from a folder of FASTQs with `scripts/make_manifest.py`.

2. Trim primers with cutadapt (BEFORE DADA2)

qiime cutadapt trim-paired \
  --i-demultiplexed-sequences demux.qza \
  --p-front-f GTGYCAGCMGCCGCGGTAA \   # forward primer (example: 515F)
  --p-front-r GGACTACNVGGGTWTCTAAT \  # reverse primer (example: 806R)
  --p-discard-untrimmed \
  --o-trimmed-sequences demux-trimmed.qza
qiime demux summarize --i-data demux-trimmed.qza --o-visualization demux-trimmed.qzv

--p-discard-untrimmed drops reads where the primer was not found (usually what you want for targeted amplicons). Action and flag names verified from the q2-cutadapt source. Primer choice by region (515F/806R, ITS1F/ITS2, etc.): `references/pipeline_steps.md`.

3. Denoise with DADA2 → ASVs + feature table

Open demux-trimmed.qzv, read the interactive quality plot, and pick truncation lengths where median quality drops (forward and reverse independently). Truncated read length must still leave enough overlap to merge pairs.

qiime dada2 denoise-paired \
  --i-demultiplexed-seqs demux-trimmed.qza \
  --p-trunc-len-f 0 --p-trunc-len-r 0 \   # ← set from the quality .qzv (0 = no truncation)
  --p-trim-left-f 0 --p-trim-left-r 0 \
  --o-representative-sequences rep-seqs.qza \
  --o-table table.qza \
  --o-denoising-stats denoising-stats.qza
qiime metadata tabulate \
  --m-input-file denoising-stats.qza --o-visualization denoising-stats.qzv

Always inspect denoising-stats.qzv: low merge or chimera-survival rates usually mean trunc-len was too aggressive (no overlap) or primers were not trimmed.

4. Summarize the feature table — note the 2026.1 change

qiime feature-table summarize \
  --i-table table.qza \
  --m-sample-metadata-file sample-metadata.tsv \
  --o-summary table.qzv

2026.1 breaking change (verified in the release notes): the old summarize visualizer was renamed _summarize, and the former `summarize_plus` pipeline is now `summarize` — so today's feature-table summarize is the enhanced summary (it also emits feature/sample frequency artifacts). Older tutorials calling summarize_plus must switch to summarize. Details: `references/version_notes.md`.

5. Assign taxonomy — VERSION-MATCHED classifier

qiime feature-classifier classify-sklearn \
  --i-classifier silva-138-99-nb-classifier.qza \   # MUST match your QIIME 2 version
  --i-reads rep-seqs.qza \
  --o-classification taxonomy.qza
qiime metadata tabulate --m-input-file taxonomy.qza --o-visualization taxonomy.qzv

A pretrained naive-Bayes classifier is pickled scikit-learn — it only loads under the QIIME 2 release it was trained on. Download the classifier built for your version from the QIIME 2 Library (SILVA 138 for 16S/18S, Greengenes2 for 16S, UNITE for ITS). Version-match traps and the train-your-own path: `references/classifiers.md`.

6. Phylogeny + core diversity

qiime phylogeny align-to-tree-mafft-fasttree \
  --i-sequences rep-seqs.qza \
  --o-alignment aligned.qza --o-masked-alignment masked.qza \
  --o-tree unrooted-tree.qza --o-rooted-tree rooted-tree.qza
 
qiime diversity core-metrics-phylogenetic \
  --i-phylogeny rooted-tree.qza \
  --i-table table.qza \
  --p-sampling-depth 1103 \           # ← choose from table.qzv rarefaction; see below
  --m-metadata-file sample-metadata.tsv \
  --output-dir core-metrics

Sampling depth is a rarefaction floor: every sample is subsampled to this many reads, and samples below it are dropped. Pick it from table.qzv to balance depth against sample retention — never guess. core-metrics-phylogenetic produces Faith's PD, Shannon, observed features, Bray-Curtis / Jaccard / weighted+unweighted UniFrac distance matrices, and Emperor PCoA .qzvs in one shot.

For stats and ordination off the exported table (PERMANOVA, custom PCoA, alpha/beta metrics in Python), export and hand off to `alterlab-scikit-bio` — that is the in-memory companion to this pipeline.

Export to hand off downstream

qiime tools export --input-path table.qza --output-path exported/   # → feature-table.biom
qiime tools export --input-path taxonomy.qza --output-path exported/ # → taxonomy.tsv

scripts/check_artifact.py reads a .qza/.qzv (it is just a zip) and prints its semantic type, UUID, and the provenance action list without a QIIME 2 install — handy for sanity-checking that an artifact is what a downstream step expects.

Self-Check Before Reporting

• Did primers get trimmed before DADA2? If --p-discard-untrimmed dropped almost

everything, the primer sequences are likely wrong.

• Were trunc-lens chosen from the quality `.qzv`, and does denoising-stats.qzv show

reasonable merge + non-chimeric retention?

• Is the classifier version-matched to the running QIIME 2 release?
• Is --p-sampling-depth justified from table.qzv, not guessed?
• Did you call feature-table summarize (since 2026.1 this is the former summarize_plus),

not a removed action name?

References