一张功能注释表可以同时包含基因名、酶编号、通路、结构域和本体条目。字段越丰富,越容易让人误以为每个结果都经过了独立验证。实际上,很多内容来自参考记录的注释转移,读表时必须知道搜索命中、转移来源与最终字段之间的关系。
本文实际安装并运行 eggNOG-mapper 3.0.0-beta6,使用官方小型测试库完成蛋白搜索及多组重新注释。测试过程中也遇到了官方自检未通过的问题,我们保留失败记录,并明确哪些后续检查已经完成,哪些结论仍不能得出。

先把软件版本与数据库版本固定下来
本次安装的是明确标记为测试版的第三代程序,源码固定到发布标签对应的提交,实际提交标识保存在复现脚本中。搜索程序使用 DIAMOND 2.2.9,运行环境为 Python 3.10。
该发布标签的使用文档针对第三代程序和第七版数据库。这里展示的字段与参数不能直接当成第二代程序的通用说明。
尤其是已有项目从旧环境迁移时,应同时核对程序、数据库和输出结构。文件仍然以相同后缀结束,不代表每一列的名称、位置和语义都没有改变。
本文使用测试版,是为了实际检查这一版本的输出行为。它不是对生产项目升级的推荐,也没有把小库试验作为完整数据库分析已经通过验证的证明。
官方小型测试库适合检查流程,不适合测准确率
本次没有下载完整的功能数据库,而是使用项目提供的小型自检数据包。包内包含蛋白输入、其他输入类型的练习文件、搜索库、注释库及预期结果。
官方测试数据说明解释了小库的构造。它保留少量查询对应的种子记录及相关注释链,使搜索和后续转移能在较小数据量上运行。
这类设计适合判断程序能否连接各个环节,却不代表真实研究中存在同样容易的检索条件。查询在小型搜索库里能够找到预先保留的对应记录,是测试设计的一部分。
因此,本文没有计算真实注释准确率,也没有把小库的执行时间写成蛋白组分析速度。可复核的内容集中在输入输出关系、字段变化和参数对照。
自检实际失败,不能把程序退出当成通过
我们先执行官方自检入口,分别运行蛋白、编码序列、基因组和宏基因组四种输入类型。
emapper.py --selftest \
--data_dir /path/to/selftest \
--cpu 1
四种输入都产生了可比较的结果,但自检最终返回非零状态,报告与预期文件不一致。这个结果必须明确保留,不能因为看到了注释文件,就把安装验证写成全部通过。
进一步核对发现,数据包中的预期文件标注的是更早的测试版快照,表头有二十五列。本次程序输出二十二列,部分字段已经发生变化。
我们没有修改预期文件来消除报错,也没有把后续的自编检查冒充官方自检通过。实际能确认的是,这组软件与测试包的精确预期比较没有通过,至少存在输出结构不匹配。
发现结构差异后,应怎样继续检查
输出结构不同并不意味着所有分析都无法使用,但也不能断言只需要改几个列名就能完全兼容。对原始记录逐字段比较,才可能进一步判断差异属于表示变化还是内容变化。
本次后续只检查边界明确的问题,包括搜索到哪些输入、相同种子能否复用、转移条件如何改变字段,以及报告中的缺失是否覆盖全部未命中输入。
这些检查使用真实软件输出,并保留完整表头。它们可以帮助理解工具行为,却不能替代未通过的官方回归验证,也不足以为生产环境给出全面可靠性结论。
如果读者正在升级已有流程,建议先拿一批已知样本做这样的列级核对,再决定是否迁移。直接覆盖旧环境,往往会让差异来源更难追踪。
八条输入为何只出现七条注释
蛋白练习从官方文件中的六条序列开始。我们再复制其中一条并赋予新标识,同时加入一条长度三百、固定随机种子生成的无关序列,总计八条输入。
随后运行完整的搜索与注释,并额外请求直系同源关系表和丢弃记录。
emapper.py -i query.fa \
-o baseline \
--data_dir /path/to/selftest/data \
--output_dir results \
--cpu 1 \
--report_orthologs \
--report_dropped \
--dmnd_block_size 0.1 \
--dmnd_index_chunks 1
最终主注释表包含七个输入标识。六条官方序列和新增复制均有结果,随机对照没有进入主表。这里的八条是输入数,七条是得到相应搜索及注释结果的记录数,分母需要明确区分。
如果直接用主表行数作为“本次共分析多少条蛋白”,就会漏掉没有结果的输入。正式统计应从原始输入名单出发,再逐步连接搜索与注释记录。
丢弃表为空,不能推断所有输入都有结果
本次丢弃表只有表头,没有数据行,但随机对照仍然没有主注释。这是一个非常实用的读表边界。
该文件并没有在本次运行中列出所有缺少结果的原始输入,因此不能把它当成完整的未命中清单。判断缺失时,仍然需要对输入标识与各阶段输出做集合比较。
可以先找原始输入中没有进入种子命中表的标识,再找有种子但没有主注释的标识,最后查看那些有注释行却缺少某个功能字段的记录。
这三类缺失对应不同问题。如果统一写成“没有功能”,就会把搜索未命中、转移未成功以及某个数据库没有记录混在一起。
相同序列的两个名称仍然保留两行
新增复制与原始序列使用不同标识,但氨基酸内容完全一致。两者得到相同种子、相同搜索分数和相同主要注释字段,主表仍分别保留两行。
这说明输出记录数不能直接当成不同分子的数量。如果上游基因目录有重复序列,后续功能计数需要先定义计数单位,再决定是否合并。
在本次例子里,复制只是教学控制,不应被解释成一个新的生物学发现。同样,实际样本里相同序列的重复出现可能具有不同来源,也不能未经核对就全部删除。
合理做法是同时保留输入标识和序列校验信息,让读者能看见哪些记录内容相同、哪些只是名称相似,再根据分析目的选择合适的统计口径。
搜索一次,再做多组注释对照
为了把搜索与注释转移分开,我们先只执行搜索,保存种子命中表,再使用这个固定文件重新注释。
emapper.py -i query.fa \
-o search_only --no_annot \
--data_dir /path/to/selftest/data \
--cpu 1
emapper.py -m no_search \
--annotate_hits_table search_only.emapper.seed_orthologs \
-o reannotated \
--data_dir /path/to/selftest/data \
--cpu 1
在与基线相同的转移设置下,重新注释得到的七条数据记录逐字段一致。比较时按输入标识建立映射,忽略时间和命令路径等运行元信息。
这个结果说明,在本次固定环境与输入下,可以复用种子表来隔离转移设置的影响。它并不意味着任意版本之间都能安全复用,也不意味着数据库更新后仍会得到相同结果。
种子表应与搜索库、程序版本和原始输入一起保存。只留一个命中编号列表,无法解释编号来自哪套数据库,也无法可靠复核旧结果。
限制直系同源关系后,变化集中在部分字段
接下来把转移关系限制为一对一,其余搜索结果完全复用。主表仍然包含原来的七条记录,但部分功能字段发生变化。
| 对照对象 | 默认转移 | 限制一对一后 |
|---|---|---|
| 第一条示例 nifJ | 五个 GO 条目 | GO 字段为空 |
| 第二条示例 nifJ | 三个 GO 条目 | 保留两个 |
| 七条主注释记录 | 全部存在 | 仍然全部存在 |
这里变化的是特定字段,不是整条记录的有无。对第一条示例而言,名称和多个其他注释仍然存在,但原先转移来的本体条目没有继续保留。
因此,统计参数影响时不能只比较注释行数。如果两次结果都为七行,却有重要字段减少,单纯报告“结果一致”就会掩盖实际变化。
本例也没有证明限制一对一就一定更正确。条件更严格可能减少某些转移来源,是否更符合研究目标,仍需要结合功能证据和参考对象判断。
指定目标类群,不等于所有字段都只来自该类群
我们还测试了把候选转移对象限制为细菌类群的设置。部分条目的本体注释和最远来源谱系发生改变,但古菌种子对应的记录及部分注释仍然保留。
这个结果不能只凭参数名称解释成“所有注释已经严格来自细菌”。实际输出中仍然出现古菌谱系,说明需要进一步检查来源处理规则。
核对该版本的注释实现后可以看到,程序会把种子自身作为一个单独的优先来源加入转移过程。已有种子注释与其他候选直系同源来源,并不完全经历同一条筛选路径。
这是针对本次固定版本的观察。若研究要求严格的来源类群约束,应继续审计各字段的实际来源,不能仅凭设置了目标类群参数就宣布约束已经全部满足。
字段置信等级不是实验验证等级
主表最后包含一个由字母和短横线组成的置信编码。它按照表头中给出的字段顺序,对多个功能字段分别标记等级或缺失。
例如,某条示例记录的基因名称标为较高等级,而本体注释标为较低等级。限制转移关系后,本体字段变为空,对应编码也随之改变。
这个等级与程序的注释转移层级有关,不是对所有功能进行实验验证后得到的等级。较高标记不能被直接改写成“该功能已证实”。
解析时应读取文件中的字段顺序说明,并检查编码长度是否匹配。若代码只按固定字符位置硬取某一项,版本变化后可能把结构域等级误读为另一个字段的等级,却仍然输出看似正常的表格。
基因名、功能编号和结构域都要保留原始含义
本次示例中,输入名称包含常见基因缩写,输出也返回名称及其他功能编号。但这些字段属于不同注释体系,不能把文件名或输入标识当成对所有功能字段的最终裁决。
如果名称与其他功能体系的解释不完全一致,应进一步查看参考条目和转移来源。直接选择自己最熟悉的那个名称写入结论,可能掩盖已有注释之间需要复核的差异。
结构域字段也需要特别小心。本次没有启用对查询序列重新进行结构域比对的选项,因此,表中出现结构域信息不等于我们已经独立运行一次完整的结构域验证。
对需要精确结构域位置或关键残基的研究,应另行检查查询上的实际比对。功能表适合作为候选线索,不能替代所有后续证据。
空值、零值和很小的期望值不能混淆
部分强命中的期望值显示为零,这是软件数值输出的表示,不意味着在数学或生物学意义上不存在任何不确定性。不能据此声称功能转移绝对正确。
短横线表示某个注释字段没有给出值,也不能直接换成数值零后参与平均。缺少某类注释与测得该项为零,是不同的数据状态。
本次主表还保留了实际输出的列名与字段内容,没有根据列名自行补写类别解释。对于版本迁移,先检查字段中实际存放的值,比只相信旧脚本对列名的假设更稳妥。
导入表格时,应把标识、编号列表和置信编码作为文本处理。否则,自动类型转换可能破坏前导字符、分隔符或一个字段里的多项对应关系。
优点、限制与本次经验
eggNOG-mapper 的优势是把搜索、直系同源信息和多种功能体系整合到同一流程,并允许复用种子命中进行注释对照。本次相同设置下的重新注释与基线一致,便于开展参数影响检查。
它的限制在于注释依赖参考库和转移规则。一个搜索分数不能同时证明每个功能字段正确,某项参数也未必覆盖所有来源路径,必须结合具体版本和输出检查。
本次最明确的安装经验是,官方自检没有通过,不能把这一事实藏在“运行成功”之后。后续完成的只是几个针对输出行为的控制实验,而不是完整验证已经补齐。
对于实际项目,可以先保留原始输入名单、搜索结果、主注释和来源信息,再建立分阶段的缺失统计。这样即使某项注释发生变化,也能追踪到变化来自搜索、转移条件还是输出结构。
获取脚本并复核结果边界
下载本组三篇复现包。安装固定版本及搜索程序,取得文中指定的官方测试数据包后,执行以下入口,脚本会保留自检返回状态及后续五组运行记录。
python3 227-eggnog/run.py /tmp/eggnog-demo \
--dataset /path/to/selftest \
--emapper /path/to/env/bin/emapper.py \
--binary-dir /path/to/diamond-bin
先核对八条输入与七条主注释,再比较同设置重新注释,最后检查一对一和类群限制后的字段变化。读者应同时保留自检失败说明,避免把这个教学练习误当成可直接上线的完整验证方案。
当项目需要固定数据库与程序版本、保留多组注释对照并追踪每次结果变化时,可通过云生信生物信息学分析服务器组织可复核的分析环境。
