⚗️ QIIME 2 HANDS-ON · TODAY

Get your machine ready before we sit down at the keyboards

Installing QIIME 2 (version 2024.10, Amplicon distribution) before the session

⬇️ STEP 0 — DOWNLOAD THE WORKSHOP MATERIALS

The materials are lightweight — a few dozen MB, so they'll download in a moment. The real time sink is the QIIME 2 install, which varies a lot depending on your OS and installation method (see below).

📦 Download workshop materials →

nc.uj.edu.pl/s/iFzZHfAjaEqRgE9

⏰ We start today at 14:30

You still have a little time to get everything installed calmly — but don't leave it to the last minute. The materials are small, but the QIIME 2 install is the variable part: depending on your OS and installation method it can take anywhere from a few minutes to well over an hour (WSL setup on Windows and the conda solver on a first install are the slowest steps). Kick it off now and show up with a working setup.

To get the workshop running with real work from minute one, install QIIME 2 before we meet. Below is the quick path for each operating system. Pick your tab and go.

📋 Before you start — check:

💾	~10 GB free disk space (the environment alone is 6–8 GB)
🧠	8 GB RAM minimum, 16 GB comfortable (DADA2 denoising likes memory)
🌐	Stable internet. Institutional VPNs and firewalls sometimes block conda channels — if it fails, try a home network

🪟 Windows RECOMMENDED PATH

QIIME 2 doesn't run natively on Windows — we run it through WSL2 (a real Ubuntu inside Windows). Requires Windows 10 (build 19041+) or Windows 11.

1. Install WSL2

Open PowerShell as Administrator and run:

wsl --install

💡 wsl --install normally installs Ubuntu automatically, but on some machines it only enables the feature without a Linux distribution. If you end up with no Ubuntu app, install one explicitly:
wsl --install -d Ubuntu

Restart your computer if prompted. After the reboot, Ubuntu asks you to create a Linux username and password (this is your sudo password — it doesn't need to match your Windows login).

2. Install Miniforge inside Ubuntu

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh"
bash Miniforge3-Linux-x86_64.sh

Accept the licence, keep the default path, and answer yes to conda init. Close and reopen the terminal.

3. Create the QIIME 2 environment

conda env create \
  -n qiime2-amplicon-2024.10 \
  --file https://data.qiime2.org/distro/amplicon/qiime2-amplicon-2024.10-py310-linux-conda.yml

4. Activate and verify

conda activate qiime2-amplicon-2024.10
qiime info

✅ If qiime info prints version 2024.10.x and a plugin list — you're done.

🍎 macOS

Works on both Apple Silicon (M1/M2/M3/M4) and Intel. On Apple Silicon, QIIME 2 runs under Rosetta 2 emulation — the commands below handle that for you.

1. Install Miniforge

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

2a. Apple Silicon (M1/M2/M3/M4)

CONDA_SUBDIR=osx-64 conda env create \
  -n qiime2-amplicon-2024.10 \
  --file https://data.qiime2.org/distro/amplicon/qiime2-amplicon-2024.10-py310-osx-conda.yml
conda activate qiime2-amplicon-2024.10
conda config --env --set subdir osx-64

2b. Intel Mac

conda env create \
  -n qiime2-amplicon-2024.10 \
  --file https://data.qiime2.org/distro/amplicon/qiime2-amplicon-2024.10-py310-osx-conda.yml
conda activate qiime2-amplicon-2024.10

Finally, verify with: qiime info

🐧 Linux

Native install via Miniforge/conda. Skip step 1 if you already have conda.

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh"
bash Miniforge3-Linux-x86_64.sh

conda env create \
  -n qiime2-amplicon-2024.10 \
  --file https://data.qiime2.org/distro/amplicon/qiime2-amplicon-2024.10-py310-linux-conda.yml

conda activate qiime2-amplicon-2024.10
qiime info

🔧 Something not working? Common pitfalls (click to expand)

Symptom	Fix
`HTTP 404` / "channel not accessible"	Corrupt download. Run `conda clean --all` and retry.
Terms of Service error / `CondaToSError`	You're on Anaconda channels. Install Miniforge (as above), not Miniconda.
WSL: log shows `Platform: win-64`	You ran the command in PowerShell instead of Ubuntu. Open the Ubuntu app and retry there.
No Ubuntu app after `wsl --install`	WSL enabled but no distro installed. Run `wsl --install -d Ubuntu`, then reboot.
Solver "hangs" for a long time	Normal on first install (~100 dependencies). Give it 15–30 min.
`conda: command not found`	You skipped `conda init` or didn't reopen the terminal.

📖 Official installation guide

docs.qiime2.org/2024.10/install — install the Amplicon distribution, version 2024.10.

🤝 Stuck? Don't sweat it.

Don't spend hours fighting it. Bring your laptop as-is — we'll sort out installation problems together at the start of the workshop. The key thing is to start today, not at 14:29.

QIIME 2 Amplicon 2024.10 · Miniforge (conda-forge) recommended · See you at 14:30 👋

🧬 STUDENT WORKBOOK · EEBG 2026

Microbiome Analysis with QIIME 2

Hands-on walkthrough of the Moving Pictures tutorial — from raw reads to taxonomy

In this workshop you'll analyse a real microbiome dataset with QIIME 2 — the most widely used platform for 16S rRNA amplicon sequencing analysis. We work through the Moving Pictures tutorial, which tracks the microbiome of two healthy adults across four body sites (gut, tongue, left palm, right palm) over time.

How each step is laid out

📖	A short explanation of what the command does and why
💡	Hints to help you construct the correct command
⌨️	A blue box → write your command here
📝	A green box → note down key observations from the output

Step 0 · Environment Setup & Data Download

Before running any analysis you must activate the QIIME 2 conda environment (installed separately to isolate its dependencies), create a working directory, and download the tutorial dataset.

✅ Complete ALL of this BEFORE the workshop:

☐ Install the QIIME 2 amplicon distribution
☐ Test it: conda activate qiime2-amplicon-2024.10 && qiime info
☐ Check you downloaded all workshop materials
☐ Ensure at least 5 GB free disk space
☐ Bring your laptop with the power cable

📝 What columns does sample-metadata.tsv contain?

Peek with: head -3 sample-metadata.tsv

Step 1 · Import Data into QIIME 2

Raw sequence data must be imported into a QIIME 2 Artifact (.qza) before any analysis. QIIME 2 needs the data type (--type) to validate and track your data. EMP Single-End means reads from multiple samples are pooled and will be separated by barcodes in the next step.

Plugin: qiime tools · Method: import

Key flags: --type EMPSingleEndSequences | --input-path <folder> | --output-path <file.qza>

💡 Hint: Input path is the folder emp-single-end-sequences. Output: emp-single-end-sequences.qza

⌨️ Your import command:

✓ Expected output: emp-single-end-sequences.qza (a few seconds)

Step 2 · Demultiplexing

Demultiplexing splits the pooled reads back into per-sample FASTQ files using the unique barcode attached to each read. The metadata file maps each barcode to a sample.

2a · Demultiplex

Plugin: qiime demux | Method: emp-single

Inputs: --i-seqs (Step 1 .qza) | --m-barcodes-file (metadata) | --m-barcodes-column barcode-sequence

Outputs: --o-per-sample-sequences demux.qza | --o-error-correction-details demux-details.qza

💡 Hint: Flags starting with --i- expect artifact inputs; --m- expects metadata; --o- produces output artifacts.

⌨️ Your demux command:

✓ Expected output: demux.qza — one FASTQ per sample; runtime ~2 min

2b · Summarise & visualise the demultiplexed data

The demux summarize command creates an interactive .qzv showing reads per sample and the quality profile — crucial for choosing the Deblur trim length.

💡 Hint: After generating the .qzv, open it at view.qiime2.org

⌨️ Your summarize + view commands:

📝 Record your observations:

At what position does read quality drop below Q30? · How many total reads were assigned? · Which sample has the fewest reads?

Step 3 · Denoising with Deblur

Deblur uses a reference-based error model to remove sequencing artifacts and infer true biological sequences — Amplicon Sequence Variants (ASVs). It needs a quality-filtering step first, then outputs a feature table of ASV counts, representative sequences, and denoising stats.

Key parameters:
quality-filter q-score → removes low-quality reads (default Q4 threshold)
--p-trim-length 120 → trim all reads to exactly this length (from the Step 2 quality profile)

3a · Quality filter + Deblur denoise

Plugins: qiime quality-filter (q-score) + qiime deblur (denoise-16S)

Outputs: --o-representative-sequences rep-seqs.qza | --o-table table.qza | --o-stats deblur-stats.qza

⌨️ Your quality-filter + Deblur commands:

✓ Expected: demux-filtered.qza, rep-seqs.qza, table.qza, deblur-stats.qza

3b · Visualise denoising statistics

Stats show per-sample read counts at each stage. Key columns: reads-raw (input) and reads-hit-reference (final ASVs). Typical retention: 40–60%.

Plugin: qiime deblur | Method: visualize-stats → deblur-stats.qzv

⌨️ Your visualize-stats command:

📝 Record your observations:

Pick a sample: divide reads-hit-reference / reads-raw — what fraction was retained? · Which sample lost the most reads?

3c · Summarise the feature table

The summary shows how many ASVs were detected and reads per sample — needed to choose a rarefaction depth.

Plugin: qiime feature-table | Methods: summarize AND tabulate-seqs

💡 Hint: For summarize add --m-sample-metadata-file → table.qzv. For tabulate-seqs the input is rep-seqs.qza → rep-seqs.qzv

⌨️ Your two feature-table commands:

📝 Record your observations:

How many ASVs (features) were detected in total? · What is the minimum number of reads in any single sample? (this sets the maximum rarefaction depth)

Step 4 · Phylogenetic Tree Construction

Some diversity metrics (Faith's PD, UniFrac) need a phylogenetic tree relating all ASVs. QIIME 2 builds it in one command using MAFFT (alignment) and FastTree (tree building).

Plugin: qiime phylogeny | Method: align-to-tree-mafft-fasttree

Input: --i-sequences rep-seqs.qza · Outputs: --o-alignment --o-masked-alignment --o-tree --o-rooted-tree

💡 Hint: Provide all four --o- outputs. The one we use later is --o-rooted-tree rooted-tree.qza

⌨️ Your phylogeny command:

✓ Expected: rooted-tree.qza + 3 intermediate files; runtime ~5–10 min

Step 5 · Diversity Analysis

Alpha diversity = diversity within a single sample (richness). Beta diversity = how different samples are from each other (dissimilarity).

5a · Core metrics (alpha + beta in one command)

The core-metrics-phylogenetic pipeline computes many metrics at once and produces Emperor PCoA plots. It rarefies each sample to --p-sampling-depth reads to equalise sequencing effort.

Inputs: --i-phylogeny rooted-tree.qza | --i-table table.qza | --m-metadata-file sample-metadata.tsv

Key param: --p-sampling-depth 500 (retains all samples; check table.qzv minimum depth) · Output dir: --output-dir core-metrics-results

⌨️ Your core-metrics-phylogenetic command:

✓ Expected: core-metrics-results/ with ~10 files incl. Emperor PCoA .qzv; runtime ~2 min

5b · Alpha diversity significance testing

alpha-group-significance runs a Kruskal-Wallis test and produces box plots.

Input: --i-alpha-diversity core-metrics-results/faith_pd_vector.qza

💡 Hint: Run this twice — once for faith_pd_vector.qza and once for evenness_vector.qza

⌨️ Your alpha-group-significance command(s):

📝 Record your observations:

Which body site has the highest Faith PD? · Is the difference between body sites statistically significant?

5c · Beta diversity significance (PERMANOVA)

PERMANOVA tests whether distances between samples differ significantly by group. Here: does body-site explain the variation in UniFrac distances?

Input: --i-distance-matrix core-metrics-results/unweighted_unifrac_distance_matrix.qza

Metadata: --m-metadata-column body-site | --p-pairwise

💡 Hint: Output → core-metrics-results/unweighted-unifrac-body-site-significance.qzv

⌨️ Your beta-group-significance command:

📝 Record your observations:

Are body sites significantly different (p < 0.05)? · Open bray_curtis_emperor.qzv, colour by body-site — what do you see?

Step 6 · Taxonomic Classification

Assign a taxonomic identity (Kingdom → Phylum → … → Species) to each ASV by comparing it to a reference database. We use a Naive Bayes classifier pre-trained on Greengenes2 (V4 region, 515F/806R primers).

6a · Classify ASVs

Plugin: qiime feature-classifier | Method: classify-sklearn

Inputs: --i-classifier 2024.09.backbone.v4.nb.sklearn-1.4.2.qza | --i-reads rep-seqs.qza → --o-classification taxonomy.qza

💡 Hint: Provide the correct path to the classifier file you downloaded before the workshop.

⌨️ Your classify-sklearn command:

✓ Expected: taxonomy.qza — taxonomic assignment for every ASV; runtime ~5–10 min

6b · Visualise taxonomy

Command 1: qiime metadata tabulate → taxonomy.qzv (table of ASV → taxon)

Command 2: qiime taxa barplot → taxa-bar-plots.qzv (interactive stacked bar chart)

💡 Hint: For taxa barplot: inputs are --i-table table.qza --i-taxonomy taxonomy.qza --m-metadata-file sample-metadata.tsv

⌨️ Your two visualisation commands:

📝 Record your observations:

In taxa-bar-plots.qzv collapse to Level 6 (genus), sort by body-site. Which genus dominates the tongue? · Which phyla are most abundant in the gut? · Is the palm microbiome different from the gut?

💭 Reflection Questions

Answer based on your own results.

Q1 · Why do we rarefy samples to the same sequencing depth before calculating diversity metrics?

Q2 · What is the advantage of ASVs over OTUs for cross-study comparisons?

Q3 · Looking at your PCoA plot: do samples cluster more strongly by body site or by subject? What does that tell you?

Q4 · Faith's PD accounts for evolutionary relationships between ASVs. When is this more informative than simple species richness?

Q5 · QIIME 2 tracks provenance for every artifact. Open any .qzv at view.qiime2.org and click 'Provenance'. What information is there?

EEBG 2026 · QIIME 2 Moving Pictures tutorial · Amplicon distribution 2024.10