CheckV 实跑教程｜完整度 100% 为什么仍不是 Complete，污染率为零又意味着什么

把候选病毒序列交给 CheckV 后，最容易出现两种过度解释。一种看到完整度百分之百，就把结果写成已经获得完整闭合的病毒基因组。另一种看到污染率为零、警告为空，就认为序列的病毒身份已经得到确认。这两种判断都把不同层次的证据合在了一起。

本篇实际安装 CheckV 1.1.1，下载并建立官方数据库，以完整的 λ 噬菌体参考、它的两个截短片段及一段细菌参考为输入，逐项阅读四张输出表。重点是把长度估计、病毒身份和末端结构分开，让最终报告中的每个结论都有对应证据。实验使用公开参考和人为截取对照，不把它当作环境样本的分类准确率评测。

先明确 CheckV 在分析流程中的位置

CheckV 处理的是单条候选病毒组装序列的质量问题，包括完整度估计、宿主区域检查和完整基因组相关证据。实际使用中，应先有候选序列的来源，例如独立的病毒识别流程或明确的参考记录，再用它补充质量判断。直接把所有组装片段投入程序，不能因为输出了数字，就把每条输入都纳入病毒数量统计。工具定位和各输出字段可查阅官方说明。

读结果时可以把问题拆成三个。第一，这条序列有什么理由被认为来自病毒。第二，在这个身份前提下，它可能占对应基因组的多少。第三，是否存在支持结构完整性的额外证据。三者相关，却不能相互替代。尤其在宏基因组中，同源蛋白命中可能出现在不同来源的片段上，得到一个可计算的估计值，并不自动解决第一个问题。

这样安排流程还有一个实际好处。如果后续发现某批候选序列大多具有明显的细菌基因特征，就可以回头检查候选筛选环节，而不是不断调整完整度阈值来补救。质量评估程序可以帮助发现异常，但不应承担整条流程中所有身份识别任务。

固定软件、数据库和输入，结果才有比较基础

本次软件版本为 1.1.1，数据库为 checkv-db-v1.5，DIAMOND 为 2.1.8。数据库归档实际下载了 1,681,539,865 字节，并校验完整摘要。运行时官方当前版本标记返回这一数据库名称，因此本文固定使用它。以后复现时，即使下载页出现更新版本，也应先记录版本差别，再解释结果变化。官方数据库变更记录还说明，不同版本调整过参考序列组成，数据库变化具有分析意义。

数据库压缩包和搜索索引是两回事。本次使用镜像中的 DIAMOND，从数据库自带蛋白文件重新建立索引，生成文件为 951,291,516 字节。只解压而未完成建库，或者把另一版本工具生成的索引混进来，都可能使运行状态和预期不一致。复现实验包记录了归档摘要、镜像摘要以及建库命令。

IMAGE=quay.io/biocontainers/checkv:1.1.1--pyh106432d_1
docker pull "$IMAGE"
docker run --rm "$IMAGE" checkv --version

# 在数据库已下载、解压且校验通过后建立索引
docker run --rm --cpus 2 --memory 10g \
  -u "$(id -u):$(id -g)" -w /work -v "$(pwd):/work" "$IMAGE" \
  diamond makedb \
  --in /work/checkv_db/checkv-db-v1.5/genome_db/checkv_reps.faa \
  --db /work/checkv_db/checkv-db-v1.5/genome_db/checkv_reps \
  --threads 2

参考 λ 噬菌体采用 NC_001416.1，核酸长度为四万八千五百零二个碱基。细菌对照来自大肠杆菌 NC_000913.3 的前五万个碱基。脚本检查完整参考的长度和序列摘要后再截取，避免把下载失败的网页、不同版本或多条记录误当作同一输入。这里的截取只服务于解释实验，不表示这些片段是实际组装得到的独立基因组。

四条输入只改变长度和来源

完整 λ 序列保留全部碱基，第二条保留其前半段，第三条只保留前五千个碱基。它们有已知的长度关系，因此适合观察完整度如何响应截短。细菌对照则提供另一个检查角度，帮助判断输出字段是否足以独立证明病毒身份。

全部输入放在同一个 FASTA 文件中，使用两个线程运行完整流程。输入标题保持唯一，长度、来源和摘要另外存档。如果日后需要根据输出表反查原序列，唯一标题比临时手工编号更可靠。运行结束后同时保留详细表，而不是只复制最终汇总表中的一列百分比。

docker run --rm --cpus 2 --memory 10g \
  -u "$(id -u):$(id -g)" -w /work -v "$(pwd):/work" "$IMAGE" \
  checkv end_to_end /work/inputs.fna /work/checkv_output \
  -d /work/checkv_db/checkv-db-v1.5 -t 2

四条输入的汇总污染率都是零，警告字段也都为空。闭合基因组相关结果表只有表头，没有数据行。这个组合正好说明，只看一两个看起来理想的字段，会丢掉结果中最值得解释的部分。

百分之五十为什么得到 51.87%

前半段确实是原始参考长度的一半，但程序并不知道我们事先指定的母序列长度。它使用数据库比较与模型估计得到预期基因组长度，再计算完整度。本次前半段对应的预期长度约为四万六千七百五十个碱基，并不是原参考的四万八千五百零二，因此估计值略高于一半。

这一差异不能直接写成程序误把一半识别为完整，也不宜据此宣称估计精确到小数点后两位。输出保留两位小数，是呈现格式，不代表误差已经小到这个量级。判断估计是否足够支持研究结论，需要连同方法、置信等级、参考匹配和适用范围一起读。

五千碱基片段得到的估计值为百分之十点七一，若按原参考长度直接计算，实际保留比例约为百分之十点三一。两个数字回答的是不同问题。前者来自质量评估模型，后者来自已知截取操作。教学对照能够解释差异的来源，真实环境序列通常没有这样明确的母序列真值，更不能把一个百分比写成测量事实。

详细完整度表还给出了基于蛋白家族信息的上下界。半段输入的这一范围约为百分之四十一点八六至六十点二八。它可以作为另一条证据阅读，但不是对当前汇总值任意加减得到的通用置信区间。报告时应保留原字段名称与方法来源，避免把不同估计机制拼成一个看似更精确的数。

完整参考得到 100%，仍然只是 High-quality

完整 λ 的基于氨基酸一致性的估计达到百分之百，置信等级为高，但最终类别仍为 High-quality。与此同时，完整基因组相关表没有记录。这并不否认输入来自已知完整参考，而是表明本次自动流程没有给出足以把该条目放进 Complete 类别的相应结构证据。

我们知道它是完整参考，是因为数据来源和记录本身提供了这个信息。程序本次给出的类别，是根据它在当前输入上识别到的证据形成的判断。将这两种来源写清楚，远比强行让软件标签与先验事实完全一致更有意义。真实数据里，来源标签也需要审查，不能仅靠文件名里的 complete 一词认定完整。

因此，文章、表格或论文中最好分别列出数值完整度、质量类别和结构证据。需要讨论末端重复、环化或前噬菌体边界时，再去看对应结果，并结合组装图和读段支持。不能为了让数字与类别看起来一致，手工把本次 High-quality 改成 Complete。

细菌对照提醒我们，污染率零不能证明病毒身份

本次五万碱基细菌片段有三十五个宿主相关基因，只有一个病毒相关基因，仍然输出了百分之六点四四的完整度，污染率为零，警告为空。这里没有出现预想中的“没有结果”或显眼警告，因此尤其适合当作结果解释的反例。

污染率字段不能被理解为对任意来源序列做了一次全面的非病毒含量测定。它与流程识别宿主区域及相关边界的机制有关。没有识别出可报告的宿主污染区域，并不意味着输入每一段都已被验证为病毒。细菌对照的宿主基因数量和来源记录，提供了与简单数字截然不同的解释线索。

在批量筛选中，不能把“完整度有值且污染率为零”直接写成病毒入库条件。应当保留独立的候选识别依据，再综合病毒与宿主相关基因、序列长度、匹配覆盖、参考身份和异常情况作判断。这些字段可以支持人工复核，却不宜在没有验证集的情况下拼成一个自创的普适分类器。

细菌对照的详细表还出现了较低的匹配一致性与覆盖比例，而蛋白家族推断范围与基于氨基酸一致性的估计差别很大。这不是让我们任选一个看起来更好的数字，而是提示应该停下来审查输入适用性。证据冲突本身就是结果的一部分，不能通过删列把冲突隐藏起来。

实际安装时遇到的失败怎样定位

首次运行完成了基因识别、蛋白家族搜索和污染检查，在 DIAMOND 阶段退出。顶层日志只提示搜索任务失败，看这个提示无法判断是内存、数据库还是权限问题。打开对应的底层日志后，才看到临时文件无法创建以及权限被拒绝的明确记录。

原因是容器以普通用户身份运行，而当时的当前目录不可写。修复时为容器指定可写挂载目录，并让复现脚本在输出目录执行搜索，随后完整流程成功退出。我们没有修改数据库、提高完整度或放宽任何质量阈值，也没有把这个错误归结为内存不足。

这个经验可以迁移到其他命令行流程。先找真正失败的子任务，再检查它自己的错误信息。输出目录可写不代表当前目录和临时目录也可写。若程序支持继续运行，还应明确当前使用的是同一份输入、同一套数据库和同一组参数，避免把缓存复用造成的结果混淆误判为修复成功。

如何把表格整理成可审核的项目结果

一个实用的交付表应保留序列标识、来源筛选依据、长度、数值完整度、估计方法、质量类别、病毒与宿主相关基因数量以及警告。结构完整性证据另列一栏，不能通过完整度数值推导填入。对于没有结果的字段，保留缺失含义，不要统一替换成零。

例如某条序列缺少可用的完整度估计，说明目前没有足够证据给出该估计，不等于它的真实完整度为零。反过来，百分之百只是当前模型与结果规则下的值，也不能外推为所有组装区域都准确无误。把缺失、零值和满值分开，后续统计质量分布时才不会悄悄改变样本含义。

如果项目比较两个环境的高质量病毒比例，还要检查两边是否经过相同的候选发现流程、长度过滤和数据库版本。否则比例差异可能来自入口条件。建议同时报告候选总数、可评估数量以及各类别数量，让读者能看出分母如何形成，而不只展示一个漂亮的百分比。

CheckV 的优势是把几类质量证据整理在同一流程内，并提供详细中间表，便于追溯。局限是估计受参考覆盖和序列类型影响，数值不能包办身份判断，也不能替代结构验证。用得好的关键，是让它承担明确的问题，而不是把所有输出都当成“病毒已经验证”的统一标签。

复现材料与阅读顺序

下载本组三篇的脚本与实测结果。包内包含输入构造方式、序列和数据库摘要、固定镜像、运行命令以及本次各张原始结果表。建议先核对四条输入长度，再读汇总表，最后用详细表解释百分之百、零污染和细菌对照这三个容易误读的位置。

第一次复现不需要修改参数。先检查能否得到相同的主要结果关系，再换成自己的候选序列。更换数据库或软件版本后，把版本作为新的实验条件记录，不应为了得到本文数字而手工调整输出。只有保留这种可追溯关系，教程中的小对照才真正能帮助后续项目判断。

当候选病毒质量判断与复核流程明确后，如需批量处理更多样本，可了解云生信生物分析与计算服务。