qiime2-amplicon

QIIME 2 双端 16S 扩增子

适用于已知引物、质量编码、预期插入片段长度和样本元数据的已拆分双端 16S 检测。此限定工作流导入测序读段，去除 5′ 引物，使用 DADA2 去噪，使用显式提供的分类器对 ASV 进行分类，并保留 .qza/.qzv 溯源信息。不要将读段数视为绝对细胞数，也不要将分类学归属视为菌株鉴定。

运行前先确认检测设置

• 确认 Phred+33、读段方向、正向/反向读段中测序时的引物序列，以及引物是否已被去除。捆绑的运行器要求引物仍存在于 5′ 端；它会锚定 Cutadapt 匹配并丢弃未修剪的配对。已修剪的读段需要直接走导入 → DADA2 工作流，并在溯源中记录该省略。
• 根据实际的逐碱基质量和错误分布选择截断位置。trunc-f/r 是去除引物后的位置。预期最大插入片段长度也不包括引物。要求 trunc_f + trunc_r - maximum_insert_length >= 12；为长度变异留出余量。该检查预测的是几何重叠，而非成功的生物学合并。
• 选择参考数据库、分类学覆盖范围、方向和训练方法均适合该检测的分类器。支持全长分类器；并非必须进行引物区域特异性训练。将其 scikit-learn 版本与已安装环境完全匹配（官方 2026.7 发行版固定为 1.7.1）。记录来源 URL、数据库版本和校验和。QIIME 当前的数据资源页面链接到 2026.4 及之后版本的外部托管分类器；其较旧的下载内容不会自动兼容。不要自动获取任意的"最新"分类器，也不要复用不兼容的序列化 sklearn 模型。仅从可信来源加载 sklearn 分类器产物：QZA 格式验证并不能使不受信任的序列化模型变得安全。
• 尽可能纳入提取空白、PCR 阴性对照和模拟群落。运行器会拒绝空的 FASTQ；请单独保留空对照 ID 并报告它们，而不是静默删除对照证据。在做出生态学解释之前评估污染。

输入文件

Manifest 是一个制表符分隔的 PairedEndFastqManifestPhred33V2 文件，且恰好包含以下表头：

sample-id	forward-absolute-filepath	reverse-absolute-filepath
sample1	/data/sample1_R1.fastq.gz	/data/sample1_R2.fastq.gz

这是该辅助工具刻意设定的窄范围 manifest 配置。请使用实际的制表符、运行时可见的字面绝对路径（在调用此辅助工具前展开环境变量），每个样本一行；此 manifest 中不得有注释/指令行或额外列。 不要对 R2 文件做反向互补。样本元数据是一个制表符分隔的文件，第一列为 sample-id，ID 唯一且与 manifest 匹配，并可选的 #q2:types 注解。包含下游所需的 协变量和生物学重复 ID。 该辅助工具会检查元数据 ID 和行结构；QIIME 在执行期间会进行完整的元数据类型/指令 验证。操作所使用的元数据会保留在产物溯源中，因此请使用去标识化的生物学重复 ID。

执行

辅助脚本位于 scripts/amplicon_workflow.py。以下命令假定技能目录为工作目录。首先在不使用 QIIME 的情况下进行验证。这些示例引物和长度是示意性的，并非通用的检测设置：

python scripts/amplicon_workflow.py validate \
  --manifest manifest.tsv --metadata sample-metadata.tsv \
  --primer-f GTGYCAGCMGCCGCGGTAA --primer-r GGACTACNVGGGTWTCTAAT \
  --trunc-f 220 --trunc-r 200 --amplicon-max 300

然后在 QIIME 2 2026.7 环境中使用兼容的分类器运行。以下针对特定研究的调用是示意性的；请通过前置的质量检查或预试验来选择长度：

python scripts/amplicon_workflow.py run \
  --manifest manifest.tsv --metadata sample-metadata.tsv \
  --primer-f GTGYCAGCMGCCGCGGTAA --primer-r GGACTACNVGGGTWTCTAAT \
  --trunc-f 220 --trunc-r 200 --amplicon-max 300 \
  --classifier compatible-classifier.qza --threads 4 --output run01

run 会立即执行，仅写入全新的输出目录，并在 QIIME 命令失败时停止。它会流式遍历每一条配对 FASTQ 记录，以捕获不匹配的 ID/顺序/数量，检查序列/质量一致性和样本比对，并对前 1,000 个读段对进行精确 IUPAC 引物匹配分析。精确匹配率低属于警告：Cutadapt 允许错配，但低匹配率也可能表明方向错误、存在接头或数据已被修剪。每个样本至少有一对完整读段对必须满足名义上的引物后截断长度。这些长度估算减去了所述引物长度；它们不模拟 Cutadapt 的插入缺失或质量过滤，也不保证任何读段对实际上能够合并。

运行器为输出集合不断演变的插件方法使用 --output-dir，在版本提供时保留 Cutadapt 统计信息和 DADA2 碱基转换产物。2026.7 的表摘要还会在 table.qzv 旁生成 feature-frequencies.qza 和 sample-frequencies.qza。它记录 qiime-info.txt、commands.json、workflow.log、输入 QC、分类器校验和以及输出产物校验和。它在报告完成之前运行最高级别的 QIIME 产物验证。 关于固定版本的运行时、实际验证范围、重启处理和科学解读，请参见 references/runtime-and-interpretation.md。

分析前检查结果

根据数据情况，在本地 QIIME 可视化环境或 QIIME 2 View 中打开 trimmed.qzv、table.qzv 和 taxa.qzv。检查质量/长度分布、各样本深度和优势类群。保留原始产物，而不是用 CSV/BIOM 导出文件替换它们：导出文件不会保留原始的溯源图。

retention-qc.json 将原始读段对与 DADA2 输入和非嵌合读段进行比较，因此修剪损失始终可见。保留比例 <50% 是一种审查启发式标准，而非通用的拒绝规则。检查 stats/stats.tsv 中的各个阶段：过滤损失提示质量/预期错误设置有问题；正向去噪后的损失包括反向去噪和合并失败；嵌合体损失则需要对文库质量和参数进行审查。在稀疏化、多样性或差异丰度分析之前，调查缺失/零样本和对照行为。这些下游分析需要单独的设计决策；本技能不会自动选择稀疏化深度。 独立的 retention stats.tsv 子命令只知道 DADA2 输入计数：它报告 raw_pairs: null 并明确命名该分母。它支持仅合并的配对 DADA2 统计信息，正如本运行器所生成的那样；它拒绝保留未合并/拼接读段的统计信息。

主要参考资料

• 当前安装入口点 和 扩增子文档。
• 导入格式。
• Cutadapt 操作 和 DADA2 操作。
• 分类器数据资源。

滚动文档可能描述的是开发版本。在将固定版本的运行器适配到更高版本之前，请在确切安装的环境中检查 qiime info 和操作的 --help。