宏基因组质粒分析

验证状态

有日期的案例（2026-07-09） — Assembly 模式 RefSeq 验证通过：

  • 3 个 RefSeq 质粒全流程 39/39 步骤通过

  • NC_002127.1（3.3kb，genomad=0.99 high / platon=3.7 low）、NC_011977.1（7.6kb ColE9-J，两个工具均判为质粒）、NC_002483.1（99kb F 质粒，genomad=0.995 high / platon=22.1 low）

  • 工具：genomad + platon，策略：majority_vote

  • 3/9 张 sciplot 图形渲染成功（assembly_metrics、plasmid_length_distribution、plasmid_score_vs_length）

  • 已知限制：annotation/typing 工具在本次运行中被禁用；6 张图形因缺少注释/分型/宿主数据而跳过

该证据只覆盖当时配置选择的 39 步路径，不代表当前 90 节点 DAG 的每个分支都已 验证。后续真实数据与 SCAPP 证据单独追踪；不能把软件契约通过与生物学验收混为 一项结论。当前插件清单为 64 个已注册工具 ID 和 90 个 DAG 节点。

metagenomic_plasmid 是 ABI 面向 Illumina、ONT、PacBio HiFi、二代+三代 混合数据和 assembly-only 项目的平台感知质粒工作流。规范拓扑位于 plugins/metagenomic_plasmid/pipeline_dag.yaml；Python 引擎负责解析逐样本输入、 条件节点、输出路径、provenance 和标准结果表。

默认路径

Illumina

FASTQ → fastp → MultiQC → 可选 Bowtie2 去宿主 → MEGAHIT → QUAST
      → geNomad → 环状/结构判定 → PlasmidFinder + MOB-typer
      → Bakta + AMRFinderPlus + ISEScan + IntegronFinder
      → MMseqs2 catalog → Bowtie2 + samtools + CoverM → 报告

ONT

FASTQ/POD5/BAM → 可选 Dorado 或 BAM 转 FASTQ → NanoPlot → Filtlong
               → 可选 minimap2 去宿主 → metaFlye
               → 可选 Medaka → QUAST → 共用下游路径

PacBio HiFi

FASTQ/BAM → 可选 BAM 转 FASTQ → NanoPlot + HiFiAdapterFilt
          → 可选 minimap2 去宿主 → hifiasm-meta → QUAST
          → 共用下游路径

二代+三代混合数据

Illumina + ONT/HiFi → fastp + NanoPlot/Filtlong
                    → 按平台可选去宿主
                    → OPERA-MS → QUAST → 共用下游路径

hybridSPAdes 和 metaSPAdes 是显式替代方案。选择替代 assembler 时会替换平台 默认工具，不会隐式双跑多个 assembler。

工具策略

默认主路径保持收敛：

  • geNomad 是默认选中的质粒检测工具；Platon、PLASMe、PlasX 和基于图的 SCAPP 路径都是可选证据，只有配置显式选择后才启用。加权投票从 plasmid_detection.tool_weights 读取权重；未选择工具的权重不会触发执行。

  • PlasmidFinder 和 MOB-typer 是默认分型工具。

  • AMRFinderPlus 是默认 AMR 路径；ABRicate 和 RGI 为可选补充。

  • ISEScan 和 IntegronFinder 默认启用；eggNOG-mapper 为可选项。

  • MMseqs2 用于跨样本 catalog 聚类；BLAST、MUMmer、clinker 只用于代表序列验证或展示。

  • MetaBAT2、MaxBin2、CONCOCT、SemiBin 位于可选 MAG 宿主基因组分支，不属于质粒分箱。

  • BWA、KneadData、Hi-C 占位节点、pMLST 和批量 Bandage 节点已从工作流 DAG 移除。

FastQC 默认关闭，因为 fastp 已输出 HTML/JSON QC 报告；只有发表附件或 QC 审计需要时 再启用。MultiQC 保持开启，用于项目级汇总。

跨样本条件节点

ABI 根据真实 sample sheet 计算是否满足运行条件：

模块

默认门槛

alpha/beta 多样性

至少 3 个具有 reads 丰度的样本

差异丰度

至少 2 组，且每组至少 3 个有效重复

FastSpar 网络

至少 20 个具有 reads 丰度的样本

不满足门槛时不会启动节点，原因会写入 tables/analysis_status.tsv 和序列化执行计划。 assembly-only 行不会被计作丰度分析重复。

满足门槛的差异分析默认使用 DESeq2 和原始 mapped counts。缺少原始 counts 时，会把 取整 coverage 明确标记为 count proxy。internal_effect_size 仅作为描述性回退，不输出 推断性 p value。

稳定结果契约

执行前会为每张声明表创建表头。因此合法的零命中运行会产生空 TSV，而不是缺文件。 核心公开结果包括：

  • sample_qc.tsv、assembly_qc.tsv

  • plasmid_predictions.tsv、plasmid_consensus.tsv、 plasmid_structure.tsv、plasmid_catalog.tsv

  • plasmid_abundance.tsv、plasmid_annotation.tsv、amr_genes.tsv、 mge_elements.tsv、plasmid_typing.tsv

  • host_profile.tsv、host_plasmid_links.tsv

  • differential_plasmids.tsv、network_edges.tsv、network_nodes.tsv

  • analysis_status.tsv

旧版标准化表仍保留，用于兼容已有消费者。

可复现性

每次运行都会写出 provenance/resource_manifest.json，并保留兼容文件 provenance/resources.json。数据库条目包含资源 ID、路径、版本、日期、来源、状态和 checksum。普通文件使用内容 SHA-256；显式列入 provenance.checksum_resource_ids 的 数据库目录使用确定性的内容树 SHA-256，除非配置中提供了上游发布方 checksum。

工具版本、解析后的输入、命令、日志和最终配置分别记录。以 NOT_CONFIGURED 结尾的 占位路径会明确标记为未配置；dry-run 通过不能证明外部工具或数据库已经安装。

常用命令

abi plan --type metagenomic_plasmid \
  --config examples/config_minimal.yaml --profile dry_run

abi dry-run --type metagenomic_plasmid \
  --config examples/config_minimal.yaml --profile dry_run

abi check-resources --type metagenomic_plasmid

生产运行前应填写数据库路径和版本、验证 sample sheet，并先执行资源与工作流检查。