alterlab-qiime2-amplicon

QIIME 2 Amplicon — 16S/ITS 微生物组分析流程（FASTQ → 特征表 → 分类 → 多样性）

用于标记基因（扩增子）微生物组分析的命令行工作流运行器入口。输入原始拆分后的双端 reads，它会按照 QIIME 2 的标准顺序依次执行 — 导入 → 引物修剪 → 去噪 → 分类 → 多样性分析 — 并讲解最容易出错的两点：在 DADA2 之前修剪引物，以及 .qza/.qzv 溯源模型。该流程将原始数据处理为结果，并把特征表交给内存分析技能（见下方路由）。

本技能基于当前版本 QIIME 2 2026.7（于 2026-07-22 发布）编写。此前名为 amplicon 的发行包已于 2026.4 更名为 qiime2，其 conda 环境文件采用 rachis- 前缀（框架包于 2026.1 从 qiime2 更名为 rachis）。变更的只有环境名称、通道路径和文件名：下方所有插件命令在这些版本中均保持不变。

何时使用此技能

当请求涉及从测序 reads 运行扩增子／微生物组分析流程时，请使用此技能：

• “在我的双端 reads 上运行 QIIME 2 16S 分析流程。”
• “我有 ITS 扩增子 FASTQ 文件 — 使用 DADA2 去噪并进行分类。”
• “构建特征表／ASV 表，并使用 SILVA 进行分类。”
• “根据质量图选择截断长度，并运行核心指标多样性分析。”
• “如何在 QIIME 2 中先修剪引物再运行 DADA2？”
• “QIIME 2 命令的正确顺序是什么？”

不适用 — 请路由至其他技能

请求实际涉及……	路由至
对已导出的特征表／距离表进行 α／β 多样性、UniFrac、PCoA 排序、PERMANOVA 分析（内存中，Python）	alterlab-scikit-bio
在 QIIME 2 之外构建／操作系统发育树、树可视化或比较系统发育学	alterlab-phylogenetics / alterlab-etetoolkit
宏基因组鸟枪法测序分类学谱系分析、MAG 组装、功能基因分析（非标记基因扩增子）	不属于此技能 — 仅支持扩增子；指出此能力缺口
RNA-seq 转录本定量（salmon/kallisto）、差异表达分析	alterlab-rnaseq-quant → alterlab-pydeseq2
变异检测 FASTQ → VCF（生殖系／体细胞）	alterlab-nf-core-sarek
蛋白质／核苷酸序列相似性搜索（BLAST+/DIAMOND）	alterlab-blast
空间转录组邻域／富集分析	alterlab-squidpy-spatial
快速进行一次性的基因／序列／数据库查询	alterlab-gget
读取／写入 BAM/SAM/VCF、对比文件处理	alterlab-pysam

此技能仅适用于扩增子（标记基因）。如果数据属于宏基因组鸟枪法测序、单细胞数据，或任何非 16S/18S/ITS 标记基因测序，请说明并停止。

工件模型（.qza / .qzv）— 请先阅读

QIIME 2 中的一切都是会记录自身溯源信息的带类型压缩工件：

• .qza — QIIME 2 工件：数据（特征表、序列、分类器） 以及嵌入其中的语义类型（例如 SampleData[PairedEndSequencesWithQuality]、 FeatureTable[Frequency]）和记录其生成过程的完整溯源图。
• .qzv — 可视化结果：可供人查看的报告（质量图、摘要、 多样性 emperor 图）。将其拖入 **https://view.qiime2.org**（离线、在浏览器中） 或运行 qiime tools view file.qzv。
• 溯源信息是可重复性的关键优势：任何 .qza/.qzv 都包含生成它所用的确切命令、 参数和插件版本。请保留工件，而不只是导出文件。

应将语义类型视为契约：某个操作只接受其声明类型的工件，因此导入（第 1 步）至关重要。

标准顺序（请勿调整）

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

引物修剪必须在 DADA2 之前进行。 DADA2 会对每个碱基的错误率建模；残留的引物／接头碱基会破坏该错误模型，并导致虚假的 ASV 增多。先使用 cutadapt trim-paired 修剪，再进行降噪。（如果读取已经去除了引物——例如 EMP 风格的数据——可以跳过 cutadapt，但要核实，不能想当然。）

0. 安装／激活环境（仅限 conda，不要使用 pip）

QIIME 2 无法通过 pip 安装；它以 conda 环境的形式提供。对于 2026.7（已在 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

环境文件名编码的是平台（linux-64、osx-64），而不是 2026.4 之前使用的操作系统运行器名称。为每个发行版单独创建环境——分类器必须与运行版本匹配，因此并行环境是常态，而非杂乱堆积。

对于其他发行版，采用相同做法，只需在环境名称和 URL 路径中替换版本；请参阅 QIIME 2 Library 快速入门。完整安装细节和环境文件对照表： references/installation.md。

大批量 DADA2 降噪和分类器训练会大量占用 CPU／RAM。在 Cem 的 M4 Max 上，这些任务可以在本地顺利运行——不要放到 API 上执行，而应在已运行 conda activate 的 shell 中运行。

1. 导入解复用后的双端读取数据（manifest）

使用 manifest（将样本 ID 映射到绝对 FASTQ 路径的 TSV 文件），以便准确控制哪些文件对应哪些样本。格式：PairedEndFastqManifestPhred33V2（已在 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 架构、单端和 EMP 变体以及 ITS 说明： references/import_and_manifest.md。 使用 scripts/make_manifest.py 从 FASTQ 文件夹生成 manifest。

2. 使用 cutadapt 修剪引物（在 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 会丢弃未找到引物的读取（对于靶向扩增子，这通常是你想要的）。操作和标志名称已根据 q2-cutadapt 源代码核实。不同区域对应的引物选择（515F/806R、ITS1F/ITS2 等）： references/pipeline_steps.md。

3. 使用 DADA2 降噪 → ASV + 特征表

打开 demux-trimmed.qzv，查看交互式质量图，并在中位质量下降的位置选择截断长度（正向和反向分别选择）。截断后的读取长度仍须留有足够的重叠区域，以便合并配对读取。

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

务必检查 denoising-stats.qzv：合并率或嵌合体存活率偏低，通常意味着 trunc-len 过于激进（没有重叠区域）或引物未修剪。

4. 汇总特征表——注意 2026.1 版本变更

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

**2026.1 破坏性变更（已在发行说明中核实）：**旧的 summarize 可视化器更名为 _summarize，原先的 summarize_plus 流程现在名为 summarize——因此现在的 feature-table summarize 就是增强版汇总（它还会生成特征／样本频数制品）。旧教程中调用 summarize_plus 的地方必须改为 summarize。详情：references/version_notes.md。

5. 分类注释——分类器必须匹配版本

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

预训练朴素贝叶斯分类器是 pickle 序列化的 scikit-learn 模型——只能在训练它的 QIIME 2 发行版中加载。从 QIIME 2 Library 下载与你的版本匹配的分类器（16S/18S 使用 SILVA 138，16S 使用 Greengenes2，ITS 使用 UNITE）。版本匹配方面的注意事项和自行训练的方法： references/classifiers.md。

6. 系统发育 + 核心多样性

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

采样深度是稀释分析的下限：每个样本都会被子采样至此读取数，低于该值的样本会被剔除。请从 table.qzv 中选择，以平衡深度与样本保留率——切勿猜测。core-metrics-phylogenetic 一次性生成 Faith's PD、Shannon、观测特征、Bray-Curtis / Jaccard / 加权+非加权 UniFrac 距离矩阵，以及 Emperor PCoA .qzv 文件。

要对导出的表进行统计分析和排序（PERMANOVA、自定义 PCoA、Python 中的 alpha/beta 指标），请导出并交接给 alterlab-scikit-bio——它是此流水线的内存内配套工具。

导出以便下游交接

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 可读取 .qza/.qzv（它本质上是一个 zip 文件），并打印其语义类型、UUID 和来源操作列表，无需安装 QIIME 2——便于核验该工件是否符合下游步骤的预期。

报告前自检

• 是否在 DADA2 之前剪切了引物？如果 --p-discard-untrimmed 丢弃了几乎所有数据，引物序列可能有误。
• 截断长度是否根据质量 .qzv 选择，且 denoising-stats.qzv 是否显示了合理的合并率和非嵌合体保留率？
• 分类器的版本是否与正在运行的 QIIME 2 版本匹配？
• --p-sampling-depth 是否根据 table.qzv 确定，而非猜测？
• 是否调用了 feature-table summarize（自 2026.1 起，这是原来的 summarize_plus），而不是已移除的操作名称？

参考资料

• references/installation.md — conda 环境文件（当前版本为 2026.7；2026.4 的 qiime2 重命名）、qiime info，以及不使用 pip 的原因。
• references/import_and_manifest.md — manifest 格式、单端/EMP/ITS 导入。
• references/pipeline_steps.md — 各步骤的标志、按区域划分的引物组、去噪 QC 解读。
• references/classifiers.md — SILVA 138 / Greengenes2 / UNITE、版本匹配、自行训练。
• references/version_notes.md — 截至 2026.7 的版本变更、qiime2 重命名、summarize 变更。

AlterLab 学术技能套件的一部分。