Bactopia 实跑教程｜流程成功不等于样本合格，怎样读懂质控标记与恢复运行

把一批细菌测序数据交给自动流程后，最让人放心的画面通常是绿色的完成提示。然而，这个提示首先回答的是任务有没有按程序结束，并不自动回答每个样本是否足以开展后续分析。本次实际安装并运行 Bactopia，故意放入一个数据量充足的教学样本和一个数据量明显不足的对照。两次工作流退出码都为零，低数据量样本却留下了多份质量错误文件。这不是前后矛盾，而是批量分析必须理解的状态层次。

文章重点是实际运行质控流程、辨认输出、检查恢复运行是否复用了任务，以及从真实报错中找到正确的修复位置。本文运行的是 cleanyerreads，不把这次结果扩展成完整的组装、注释或耐药分析性能评测。设计数据也不是临床或环境测序，不能据此承诺真实项目的准确率和运行时间。

一、先明确工具替你管理了什么

Bactopia 把细菌基因组分析中的输入整理、软件调用、结果组织和任务调度放进统一流程。对于拥有多个样本的项目，它的主要价值是减少每个样本各写一份脚本造成的路径错误、参数漂移和结果目录混乱。底层工具的判断规则仍然存在，研究者依旧要解释样本量、读段质量、覆盖深度和后续分析的适用条件。统一入口能提高一致性，却不能替代对输入和输出的判断。

官方提供多种工作流。选择之前，应先写下当前问题需要哪一步结果。如果只想检查数据是否适合继续分析，先运行质控就是合理的小实验。直接把所有可选流程都打开，会让失败原因和生物学问题纠缠在一起。这里按官方 cleanyerreads 说明选择质控入口，同时以本次安装版本的帮助输出核对参数名称。

这种集成工具也有代价。运行环境不只包含一个可执行文件，还包括 Nextflow、插件、容器镜像和可能访问的网络资源。安装主程序完成，只代表依赖准备的一部分。首次运行卡住时，应先识别当前停在下载、配置解析还是实际分析，不能把任何等待都解释为数据太大。

二、实验怎样设计，哪些结论不能外推

本次使用 Bactopia 4.1.0、Nextflow 26.04.6 和 nf-bactopia 2.1.7。主程序容器和实际执行的三个依赖镜像都记录了摘要。质控结果显示 fastp 为 1.3.1。镜像标签方便阅读，摘要才用于核对具体镜像内容。工作流额外下载过若干依赖，但任务记录没有显示它们参与本次计算，因此不能把下载清单直接写成实际运行的软件清单。

输入源是公开的大肠杆菌 K-12 参考序列 NC_000913.3。脚本检查序列校验值后，取前二十万碱基作为教学片段，再按固定随机种子生成长度为一百五十碱基的双端读段。片段长度设在三百五十至五百五十碱基之间，不人为加入测序错误或接头。充足组生成三万对，低数据量组只生成一百对。两组差别清楚，适合观察质量条件如何触发。

这里将预期基因组大小填写为二十万，是因为实验只围绕这个设计片段计算深度。真实大肠杆菌项目不能照抄这个数字。若把真实基因组长度错误地填小，估算深度会被抬高，样本可能看起来比实际更充分。应依据项目对象和可靠先验选择长度，并明确它是参考长度、估算长度还是组装长度。

合成数据也有明显边界。所有碱基质量被设为高值，没有模拟污染、混合菌、文库偏倚和真实错误分布。它适合检查流程行为和计量单位，不适合评价真实样本的清洗准确率，更不能用它得出某种测序平台的普遍质控阈值。

三、把样本清单当作分析输入的一部分

本次样本清单包含 sample、runtype、genome_size、species、r1、r2、se、ont、assembly 等列，双端输入使用 paired-end。样本名不仅出现在报告中，还会参与输出路径组织，因此应保持唯一、稳定，并避免在分析中途更名。双端文件的对应关系尤其值得单独检查，文件存在并不意味着两个文件来自同一样本。

初始准备阶段实际运行过 bactopia prepare，并检查了它生成的清单结构。随后重复准备时，辅助命令访问在线基因组大小资料发生等待。针对这个已经明确物种字段和设计长度的小实验，最终复现脚本直接写出相同结构的清单，避免重复的在线查询。这个处理解决的是输入元数据已知情况下的环境依赖，不是对未知样本省略物种判断。

文章使用的运行入口如下，清单、参数文件和资源配置的生成代码均包含在复现材料中。不同版本示例可能出现不同参数名称，因此复制命令后还要执行本机帮助核对。本次实际生效的是 --samples。

bactopia --wf cleanyerreads \
  -profile docker \
  -c limits.config \
  -params-file parameters.json \
  --samples samples.tsv \
  --outdir results \
  --max_cpus 2 \
  --max_memory 6.GB \
  --max_retry 1

不要只保存这条命令。清单中的路径、两个读段文件、预期长度、参数文件、环境版本和运行日志共同构成可复查的输入。只留下最终报告，后面很难判断差异来自新数据、不同参数还是软件环境变化。

四、先看读数，再看碱基数和深度

实际结果如下。读段条数将两端相加，不能误写成读段对数。质控前的九百万碱基来自六万条读段，而不是六万对。低数据量组两百条读段对应一百对。统计表若没有写清单位，后续计算覆盖深度时很容易出现两倍误差。

充足组清洗后仍有六万条读段，但少了一千一百个碱基。原始 fastp 报告将这部分归入接头剪切，共涉及二十四条读段。由于生成脚本没有加入接头，这个结果提醒我们，工具的分类名称描述的是算法采取的操作，不能自动当作输入真实存在接头的独立证据。本次没有逐一分析这些局部序列为何触发剪切，也没有开展替代参数对照，因此不能进一步宣布某个算法机制已经被确认。

正确做法是保留这条异常线索，把剪切前后的序列、报告中的接头计数和具体版本放在一起复查。高质量分数并不保证算法完全不改动读段，同样，出现少量剪切也不能直接判断整批数据有问题。先核对数量级和影响范围，再决定是否需要扩大排查。

充足组两个单端统计的最终深度各约为二十二点四九七二倍，两端合计才约为四十四点九九四五倍。这是碱基总量除以设计片段长度得到的平均量，不是通过比对得到的每个位点深度。即使平均值合适，真实样本仍可能有低覆盖区、污染读段或不均匀覆盖，因此不能省略后续按研究问题进行的比对和覆盖检查。

五、最容易误判的地方是质量失败仍可正常结束

低数据量组在输入整理阶段产生低读数和低碱基量错误文件。错误说明显示，两百条总读数低于七千四百七十二条条件，三万碱基低于二百二十四万一千八百二十碱基条件。到了质控阶段，还能看到低覆盖条件对应的错误文件，明确提到二百万碱基与十倍覆盖要求。这里记录的是本次运行的实际触发条件，不应把它们抄成所有项目的固定质量标准。

需要特别纠正一种过度简化的说法。这个样本并没有在输入整理后完全停止一切处理。任务记录显示它仍然执行了质控，生成了质量统计和带错误后缀的读段文件。它的任务状态也是完成，不能因为状态栏是绿色，就将它和普通清洁输出一起无条件送往下游。

至少应区分三层状态。第一层是整个工作流是否正常结束，第二层是某个计算任务是否成功执行，第三层是样本是否满足当前质量条件。前两层主要反映程序执行，第三层才与样本能否继续分析直接相关。把这三层合并成一个“成功”字段，会隐藏最关键的质量信息。

批量项目可以据此设计交付表，每个样本同时记录任务状态、质量错误类别、有效读数、估算深度以及是否进入下一步。对失败样本保留原始读段和原因，不要通过降低条件来让全表变绿。确实需要调整阈值时，应给出对象差异或分析目标的依据，并记录调整后对结论范围的影响。

六、恢复运行要看任务记录，不能只看命令

第一次正式运行共有五个任务，均显示 COMPLETED，包括两个样本的输入整理、两个样本的质控以及一个汇总任务。随后保持输入文件、参数和工作目录不变，追加 -resume 再次执行。第二次记录中，同样五个任务全部显示 CACHED。这才是本次确认缓存复用的直接证据。

bactopia --wf cleanyerreads \
  -profile docker \
  -c limits.config \
  -params-file parameters.json \
  --samples samples.tsv \
  --outdir results \
  --max_cpus 2 \
  --max_memory 6.GB \
  --max_retry 1 \
  -resume

恢复运行并不是只要结果目录存在就能生效。运行缓存、工作目录中的任务产物和可识别的输入共同影响能否复用。若将读段重新压缩、换路径、改参数或清理工作目录，不能预设仍然全部命中。复现脚本在一次生成数据后立即执行两轮命令，避免在两轮之间重新生成压缩输入，这是为了让对照条件保持清晰。

还要避免另一个误读。第二次运行更快，只能说明本次任务得到复用，不能据此声称算法处理原始数据变快。性能比较应区分首次运行、依赖下载和缓存恢复。本文不报告通用的加速倍数，因为这个极小数据集和依赖准备过程不能代表实际项目负载。

七、真实遇到的安装问题怎样定位

第一次启动在远程配置读取处等待。检查运行栈后，确认还没有进入实际质控计算，而是在网络配置解析阶段。对本次不需要机构配置的隔离实验，参数文件显式将 custom_config_base 设为空值，随后流程继续。这类现象应通过日志和实际等待位置定位，单纯增加线程通常没有帮助。

另一次报错来自资源声明不一致。控制运行的容器先设四吉字节限制，而工作流任务请求六吉字节，Nextflow 在启动任务前就拒绝了这个配置。后来把控制容器上限设为八吉字节，单个任务仍限六吉字节，队列和并发任务数均设为一。这里说明的是实验如何满足调度检查，不是建议所有数据都固定使用这些数值。

新目录首次初始化插件时还出现过域名解析失败。本次复用了前一次已经成功下载的同版本插件，并校验了一百一十八个文件的摘要。不能把任意来源的同名目录当成可靠缓存，也不能因为主镜像已固定就认为插件版本自然固定。最终结果同时保存了插件文件校验信息与实际任务镜像摘要。

这些问题共同说明，排错最好先判断故障所在层次。配置网络、依赖获取、资源检查、输入质量和算法执行分别需要不同证据。一直重跑完整流程会消耗时间，也可能掩盖第一次失败留下的线索。保留原始日志，再做范围最小的修复，才能解释为什么后一次运行成功。

八、适合什么场景，使用前还要做哪些判断

Bactopia 适合需要统一管理多个细菌样本、希望保存参数和运行轨迹的分析工作。它的优势在于组织过程，便于把相同规则应用到整批数据，并利用任务缓存减少重复计算。局限是依赖层次较多，目录和状态语义需要学习，而且流程默认选择不一定适合特殊物种、异常文库或非常规输入。

本次最值得带回项目中的经验，是把输出目录本身纳入检查。程序返回零以后，仍要逐样本查看质量错误、正常输出与异常输出的区别，再核对下游实际接收了哪些文件。这样的检查比只截一张成功界面更接近真正可交付的分析。

下载本组复现材料可获得生成脚本、固定环境信息、两轮任务记录、原始质量报告和结果核对值。基础安装和参数含义可继续查阅Bactopia 官方安装说明与完整使用指南。本文实跑范围止于质控，后续组装和注释仍需单独验证。

当这套逐样本核验方法进入多批次项目后，如果需要统一保存软件环境、运行日志和分析目录，可以了解云生信生物信息分析环境服务。