software

MetaPhlAn 合并结果退出码为零,为什么丰度矩阵却是空的?

作者:发布于 2026-11-15约 11 分钟阅读
退出码为零,结果却是空表。原版合并程序三次对照,分别改数据库标识和样本文件名。。同库不同名,样本 A 和 B 均正常出现,原谱缺少的物种行会在连接后补零。不同数据库,退出码 0,输出文件 0 字节,核对数据行与列名才能发现问题。文件名重复,不同目录产生两个同名 A 列,样本身份必须能从文件追溯到项目清单。

一批宏基因组样本分两次完成分析,最后一步合并丰度表。任务系统显示运行成功,绘图程序却读不到任何物种。我们在 MetaPhlAn 4.2.6 的原版合并工具中复现了这个情况,两份输入都能读,程序也正常退出,唯一的变化是第二份表声明了不同的数据库标识。另一个对照更隐蔽,两份表确实合并成功,但两个样本列竟然同名。下面用同一对可手算的样本说明怎样检查合并、怎样解释补出的零,以及为什么有些丰度列加起来会超过百分之百。

在动手合并前,确定行和列各代表什么

MetaPhlAn 使用类群特异的标记基因描述微生物群落,第四版把大量尚未有培养代表的物种水平基因组簇纳入可分析范围。读段匹配到标记,软件据此估计类群相对丰度。由此产生的分类谱与全读段逐条归类的结果具有不同的证据来源。菌株之间标记是否足够可区分、新采样环境里基因组是否被数据库代表、测序深度是否能稳定覆盖这些标记,都会影响哪些类群最终出现。拿到谱表只能说明某个分析条件下的估计,不宜从一个缺行直接推断样本中的生物绝对不存在。MetaPhlAn 4 方法论文

默认分类谱的行标识可以包含从较高层级逐步展开的完整谱系。属于一个物种的丰度可以同时体现在它的属、科以及更高层级。若将这些行全部相加,同一群落成分会在树的不同层次反复出现。合并多个样本前要先决定是制作物种矩阵、属矩阵,还是保留所有层级供向下追溯。原始合并表保留多层信息很有价值,但下游统计所用层级应当明确。样本则以输入文件的名称生成列名,因而文件放在哪个文件夹、项目表中怎样称呼它,未必就是最终矩阵看到的列名。作者的分析与输出文档

退出码为零,结果却是空表。原版合并程序三次对照,分别改数据库标识和样本文件名。。同库不同名,样本 A 和 B 均正常出现,原谱缺少的物种行会在连接后补零。不同数据库,退出码 0,输出文件 0 字节,核对数据行与列名才能发现问题。文件名重复,不同目录产生两个同名 A 列,样本身份必须能从文件追溯到项目清单。
原版合并程序三次对照,分别改数据库标识和样本文件名。

实跑经验 · 让两个样本共享一种菌,再各自保留一种

实验没有调用原始读段做标记基因比对。为隔离多样本合并的行为,我们按照原版工具读取的格式构造两份简化谱表,用透明的教学标识代表数据库以及类群。样本甲的未分类为二十,三个示例物种中甲种占五十、乙种占三十,丙种没有记录。样本乙的未分类为四十,甲种占十、丙种占五十,乙种没有记录。每份表还保留细菌层和示例属层的汇总。第一次两表用相同数据库标识和不同样本文件名,第二次只改数据库标识,第三次恢复数据库一致,但在两个目录里使用相同的文件名。运行脚本、输入和实测输出

python3 103-metaphlan/run.py /path/to/MetaPhlAn work
head -n 4 work/matched/merged.tsv
wc -c work/mixed/merged.tsv
head -n 2 work/duplicate_names/merged.tsv
条件 实测退出码 输出表头或文件状态 交付时应核对什么
同库、不同样本名 0 clade_name、A、B 两列能与样本清单一一对应
不同数据库标识 0 输出文件为 0 字节 程序提示输入版本不一致
同库、相同文件名 0 clade_name、A、A 两份样本数据存在,列名发生碰撞

第二个条件最容易骗过批量任务系统。该版本先为输出打开文件,碰到不同的首行标识后在终端打印提示,从合并函数返回。这条路径没有把失败转换成非零的进程状态,因此系统只检查退出码就会把空文件当成成功结果。更可靠的验收是要求输出非空、含有正确的列头、样本列数与输入清单相符,并且至少有符合预期格式的数据行。要检查的是这几项具体结果,单看屏幕有没有抛异常或文件路径是否存在都不够。该版本合并程序源码

第三个条件中,两份文件所在目录本来不同,但是合并脚本按文件基本名生成列名,还会处理名称中的特定后缀,文件夹名称不会进入列名。于是两个列头都成了甲样本的代号。若随后用另一个读表工具打开,库还可能自动给重复列附一个数字后缀,制造出看起来已经区分了两个样本的假象。此时后缀只反映读取顺序,没有恢复样本真实身份。修复应回到原始清单,让每份文件具有唯一且可追溯的样本标识,然后重做合并,核对关键类群在修正前后的列对应关系。

同库合并出来的零,到底从哪里来

第一轮的输出把两个样本出现过的谱系取并集。甲种在两份输入都有记录,输出里的数值为五十和十。乙种只在样本甲内出现,输出为三十和零,丙种只在样本乙内出现,输出为零和五十。查看两份原始输入,会发现这两个零是做表格连接时补上去的。工具在这里没有回去重读另外那个样本的测序文件,也没有为缺行物种做新的置信检验。所以从矩阵可知的是某条输入谱系没有估计行,还需要原始比对与标记覆盖才能判断是低于检测能力,还是有足够材料支持缺席。

合并后的行 样本甲 样本乙
未分类 20 40
细菌汇总层 80 60
示例属汇总层 80 60
物种甲 50 10
物种乙 30 0
物种丙 0 50

试着把样本甲的六行相加,会得到二百六十,样本乙得到二百二十。这个合计同时计入了细菌汇总、属汇总和物种行,重复统计了分类层级之间的数量。若问题是物种组成,固定使用三个物种行,样本甲可归入这些物种的总量是八十,样本乙是六十。再把各自的未分类项分别加回,在本例两个样本都回到一百。真实数据的谱系更复杂,有的记录可能只落到更高层,或者还带有更细的菌株级标签,不能把“凡是名称中出现物种标记的行”全部无差别计入物种层。

若想只比较这三个已分类物种内部的构成,也可以另外计算一个明确定义的条件比例。样本甲的甲种占五十除以八十,即百分之六十二点五。样本乙的甲种占十除以六十,约百分之十六点七。这两个数回答的是已纳入物种集合内部的相对份额,原谱上的五十和十则保留了未分类所占空间。作图前先选定哪种分母更符合生物学问题,然后在图注中写明。若使用重新归一的矩阵,最好同时显示未分类比例,否则数据库对两批样本覆盖程度的差别会被隐藏。

多个批次的数据库标识为什么值得认真修

标记数据库更新可能改变哪些类群可被识别、某个类群有哪些可用标记,甚至改变未表征类群的名称和层次。两个版本中拼写完全相同的物种名,并不保证丰度由完全相同的标记证据估计。若跨批次混库,某个类群恰好仅在后一个版本中可识别,它在旧批次的一整列零就可能是数据库差异,而非患者组与对照组真实分离。因此不应简单修改首行文字让合并通过。先查每一批实际用了哪套标记资源、相同预处理和参数是否能重跑,再决定能否进行物种级的定量比较。

任务交接时可以维护一个样本清单,每行写库标识、软件版本、样本唯一名、原始谱文件名和当时使用的命令。先读每份谱的首行,把不一致的样本单独列出,再核对它们是否恰好对应某个采样时期、实验批或研究分组。若技术批次与目标表型完全重合,即使强行拼出数值矩阵,也无法单凭该矩阵区分技术来源和生物来源。若短期只需要审阅各批内部结果,可以在同库样本内各自合并,继续检查各批数据质量,把跨批定量对比留到有可比证据时再做。

同样重要的是在合并之前核对样本列命名。给每个样本一个稳定标识,把批次、取样部位、时间点等元数据放到单独的样本表里,再根据标识一对一关联。不要让左表一个标识对应右表多行,也不要依赖文件在系统中的列出顺序。可以挑一条在某份输入里独有的示例物种,从原单样本谱一路查到合并表所在列,再查到对应的样本说明。若数值落在不该出现的另一列,应先修正标识映射,核对通过后再开展差异丰度分析。

这里有一个可以直接复用的合并前检查。把准备传给原版工具的文件按同一顺序交给下面的短脚本,读取首行标识,并按本版工具的规则计算拟生成的样本名。若不同目录会导出重名列,它会在昂贵的下游分析之前报出问题。这里沿用的是本文所测试版本的命名规则,若项目对样本另有命名约定,就应从清单显式建立映射,而非沿用目录中的偶然文件名。

from collections import Counter
from pathlib import Path
import sys

paths = [Path(f) for f in sys.argv[1:]]
if not paths:
    raise SystemExit("请提供待合并的谱文件")
catalogs = set()
names = []
for path in paths:
    with path.open(encoding="utf-8") as stream:
        first = stream.readline().rstrip().split("\t")[0]
    if not first.startswith("#"):
        raise SystemExit(f"缺少标识 {path}")
    catalogs.add(first)
    names.append(path.stem.replace("_profile", ""))
duplicates = [name for name, n in Counter(names).items() if n > 1]
if len(catalogs) != 1 or duplicates:
    raise SystemExit(f"检查数据库 {sorted(catalogs)} 和重名列 {duplicates}")

做层级筛选时还要留意分类命名体系。本文的默认谱系是用竖线分开的,作者的合并脚本也为另一种分类谱提供了专门的输入选项。两类文件的列位置和谱系分隔写法可以不同。若只靠“物种名字里有一个下划线”这样的规则提取,很容易把属级候选、未定名的类群或包含物种路径的更深层行选错。可以先按该格式的分隔符取最后一个谱系节点,再在最后节点上判断目标层级,并另列未分类条目。抽查一个包含更细层级的样本,确认原来的物种行和它的子行没有都进入同一个总和。

最后,在合并完成后把单样本原谱的摘要和文件大小也纳入验收记录。若某一批输入文件在分析后被替换,即使样本名和数据库首行都一样,数值仍有可能已经改变。给每个输入保存内容摘要并记录生成日期,能够区分矩阵因重跑发生变化与文件名重复造成的错位。尤其是长期队列,一个样本经常会在质控修订后重做,保留这个对应关系有助于只重建实际受影响的统计。

做差异分析前,用三处反查验收矩阵

第一处查行。选一条两个样本都有的谱系,复算合并前后的数值并核对完整谱系字符串,再选一条只在一份表出现的谱系,检查对照列的零从何而来。第二处查列。比较预期样本集合与实际表头,两者要一一对应。第三处查分母。分别把选定层级的行加总,并单列未分类,让读者知道某样本是否只有部分质量能落入目标集合。如果输入中还有未指定的上位类群,不要为了凑到一百而擅自分摊给已知物种。

若要用这些零计算出现率,可以把“原谱有该行”作为一种明确定义的检测规则,并保留测序深度或标记覆盖等适用条件。不同深度样本的补零比例往往不同,尤其在研究稀有成员时,最好同时看阳性样本数、各组可评价样本数和低深度样本的影响。若下一步要做对数变换,则还要记录零值如何处理,不能在不留说明的情况下给所有格子加上任意小常数。这些动作各自改变了矩阵的含义,只有追溯到原始谱、合并规则与选定分母,结果才方便他人复算。

当多个队列需要按同一标记库重做原始读段分析时,可用样本清单、测序量和已核实的数据库版本向云生信生物分析服务器团队评估批量重跑安排。

把知识用于当前任务

下一步可以直接开始分析

按研究目标查找在线工具、课程、计算资源或完整分析服务。

按目标找方案仍有疑问,联系客服 ↗