software

TRUST4 报告组件实跑,频率加起来等于四为什么不一定是算错了

作者:发布于 2026-11-18约 11 分钟阅读
TRUST4原生报告组件原创输入八条输出频率和4,新增TRB使原记录0.9变0.09,纳入partial使IGH0.6变0.05455,都是分母变化非原支持减少。

把免疫组库结果导入表格后,很多人会先检查频率列是否加起来等于一。这个习惯通常有用,但前提是整列使用同一个分母。TRUST4 的报告可以同时包含不同受体链,某些链类别分别归一化。如果把这些行混在一起检查,就可能把合理结果误判为错误,也可能为了让总和变成一而进行一次没有生物学依据的重归一化。

这次实际安装 TRUST4 1.1.10,调用其原生报告组件,输入自己编写的九条示意性注释记录,完成基础、增加一种链的记录、纳入部分序列三组对照。基础输出八行,频率总和恰好为四。这个结果来自原生程序,而不是我们重写的计算器。本文实跑范围是报告生成,未运行读段提取、受体组装或参考序列注释,不把短小示意序列当作真实生物样本。

TRUST4原生报告组件原创输入八条输出频率和4,新增TRB使原记录0.9变0.09,纳入partial使IGH0.6变0.05455,都是分母变化非原支持减少。
实际执行trust-simplerep.pl的三组对照,所有输入字段与短序列均为教学构造。没有执行读段提取、组装、参考比对或细胞克隆验证。

从 RNA 测序到频率表,中间有几层不同的对象

TRUST4 面向免疫受体序列重建,可以处理普通转录组及带细胞条形码的数据。完整流程会从输入中寻找候选读段,组装序列,进行基因与互补决定区注释,再整理报告。最终频率表只是这些步骤中的一个输出视图。读段、分子、组装序列、受体链和细胞之间没有天然的一比一关系,因此必须先问一行结果到底代表什么。

以普通转录组为例,某条受体链可能被较多读段支持,这既可能与相关细胞数量有关,也可能与表达量、捕获效率和测序覆盖有关。不能看到读段支持增加,就直接断言携带该受体的细胞按同样倍数扩增。只有当实验设计和计数规则支持细胞或分子层面的解释时,才能使用相应的分母。软件提供某个数字,并不自动赋予它细胞比例的含义。

同样,一个细胞可以表达多条受体链,某些分析又需要知道这些链是否来自同一细胞。没有条形码或配对证据时,单凭两条链分别丰度很高,不能把它们拼成一对。结果表中的链类别与细胞类型也不是完全相同的字段。适合的做法是在分析开始前写清输出单位、受体范围和配对要求,再选择后续汇总方式。完整工具用途与输入选项可核对官方仓库说明。

先用可手算的小输入检查原生行为

本次原创输入包含八条完整状态记录和一条部分序列记录。八条完整记录分别代表重链两条、两类轻链各一条、甲链两条和乙链两条。它们的支持数依次设为六与四、八与二、三与一、九与一。另放入一条支持数为一百的部分重链记录,用来检查默认过滤和显式纳入的区别。

序列采用自编的短核苷酸字符串,基因字段只提供软件识别链类别所需的示意标签。输入中的相似度和完整状态也是人为设置的格式字段,没有经过组装或真实参考比对。这种输入不能用于评价受体识别能力,却非常适合检验报告分母。因为每一个数都能手算,如果输出与预期不同,可以直接追踪到某一类记录,而不必在庞大测序文件中猜测。

类别 完整记录支持数 基础结果中的频率
IGH 重链 6、4 0.6、0.4
IGK 与 IGL 轻链 8、2 0.8、0.2
TRA 甲链 3、1 0.75、0.25
TRB 乙链 9、1 0.9、0.1

默认报告没有纳入那条部分序列,所以九条输入产生八条输出。观察上表,重链内部频率为一,两类轻链合并后为一,甲链内部为一,乙链内部为一,总和自然是四。这里的四对应本次出现的四个归一化集合,不是程序把每条记录重复计算了四遍,也不是四个细胞或四个克隆群的数量。

这个对照还提醒我们不要只凭概括性文档猜分母。工具文档可能用较粗的 B 细胞受体与 T 细胞受体分类介绍结果,而具体版本的报告实现使用更细的链类别。本次实际运行中,甲链与乙链分别归一化,两种轻链合并归一化。我们核对了安装版本的脚本和输出,并保留脚本摘要。换版本后应重新检查,而不是把一个历史结论永久写进分析模板。

安装、运行和结果复算

报告组件随 TRUST4 环境安装,本次直接调用原生 Perl 脚本。外层 Python 只负责写入原创记录、执行命令和读取结果,没有替代工具的报告算法。读者既可以运行附件中的驱动,也可以把自己的原生中间表交给报告组件,比较参数改变后哪些行被纳入、哪些分母发生变化。

micromamba create -n trust4-demo -c conda-forge -c bioconda \
  trust4=1.1.10

python run.py \
  --report-script /path/to/trust4-demo/bin/trust-simplerep.pl \
  --work trust4-report-output

perl /path/to/trust4-demo/bin/trust-simplerep.pl \
  sample_cdr3.out > sample_report.tsv

路径需要替换成实际安装位置,驱动的输出目录必须尚不存在。三组实验分别保留输入、原生输出和错误日志,并检查每次原生进程退出状态。实际三组都以成功状态结束。这里没有下载或使用参考序列数据库,也没有用报告执行时间代替完整组装流程的计算时间。报告组件很快,不意味着上游大规模读段处理具有相同资源需求。

复算时可以按记录标识关联输入与输出,避免根据行号对应。程序会按支持量排序,改变计数后行次序也会改变。如果把第一个输出行当作第一条输入记录,就会制造并不存在的结果差异。另一个常见问题是把表头前的井号当作注释而丢弃整行,导致列名被第一条数据代替。读取时应明确指定制表符,并确认实际列名、行数和支持量。

增加乙链记录,只改变哪个分母

第二组实验在基础输入上增加一条新的乙链记录,支持数为九十,其他记录完全不动。原来乙链两条记录的支持数仍是九和一,但频率从九成与一成变为百分之九与百分之一。新增记录占九成。与此同时,重链、轻链和甲链的所有频率保持不变,频率总和仍为四。

这个结果能直接区分两种解释。如果软件把所有记录统一归一化,新增九十份支持会改变每一行的频率。实际只有乙链集合发生变化,说明原生报告使用的是该集合内部的支持量。分析时不需要猜测,只需设计一个只改变一类证据的输入,观察其他类别是否跟着变化,就能验证分母规则。

对照项目 基础输入 新增乙链后 纳入部分重链后
原重链甲记录频率 0.6 0.6 约 0.05455
原乙链甲记录频率 0.9 0.09 0.9
输出记录数 8 9 9
全表频率之和 4 4 约 4

真实项目里也会遇到类似情形。某个样本的乙链记录数量明显增加,而重链频率分布看起来几乎不变,这未必矛盾,因为两个结果可能使用不同分母。比较组间变化时,应明确正在比较类别内部结构,还是比较不同类别的整体占比。如果要研究后者,需要重新定义有意义的总量,并证明不同类别的计数可以放在同一尺度上。

直接把整张表的频率再除以四,虽然能让总和变成一,却会让每个归一化集合得到相同的总权重。这样得到的四类整体比例是人为设定的,和它们原始支持量多少没有直接对应关系。若把这种表画成细胞组成饼图,图形会很整齐,但含义已经改变。是否重归一化必须由研究问题决定,不能以满足形式上的总和为目的。

过滤规则改变以后,留下来的频率也会变

第三组没有改变基础输入,只给原生报告增加纳入部分序列的选项。原来支持数为一百、完整评分为零的重链记录进入输出,其氨基酸字段标记为部分序列。重链分母从十变为一百一十,原来支持数为六的记录频率从六成下降到约百分之五点四五,支持数为四的记录则下降到约百分之三点六四。

这两条完整记录的原始支持数一条也没有减少。变化来自纳入集合扩大,而不是它们在样本中突然降低了表达或细胞数量。只比较前后频率,会把过滤策略的变化误认为生物变化。因此,在对不同批次结果做合并之前,必须核对是否使用相同的部分序列处理、低支持过滤、条形码筛选和计数单位。

还要注意,全表频率总和几乎没有变化,仍约等于四。也就是说,检查总和能够发现某些错误,却不能发现所有不一致。两张表可以同时满足各类别归一化规则,但包含不同记录集合。至少应同时保存输入记录数、输出记录数、被排除类别及支持量,再比较频率。单独一个总和检查并不能代替完整的数据审阅。

部分序列是否应该纳入,没有一个适用于所有任务的答案。如果任务需要完整互补决定区序列进行特异性比较,不完整记录通常不能与完整序列直接混为同类证据。如果任务是评估流程回收情况,保留部分序列的数量又可能很有价值。关键是把用途分开,并在用于下游比较的表中明确标识状态,而不是为了增加结果数量统一放宽条件。

读段计数、条形码计数和克隆定义要分别约定

原生报告还支持条形码相关汇总,但切换计数模式并不是给现有支持量换一个列名。只有输入标识和上游处理确实保留了相应条形码结构,才能按这种模式解释输出。本次输入没有真实细胞条形码,所以没有把条形码模式作为细胞计数实验,也没有根据几个示意名称推断细胞来源。

在单细胞项目中,即使每条受体记录能够对应细胞,克隆定义仍需要另行约定。按某条链的核苷酸序列合并、按氨基酸序列合并、要求基因调用一致,或者要求成对链一致,会得到不同的集合。分析团队应在计算多样性和共享克隆之前固定规则。否则,两个样本“共享多少克隆”的差异可能来自分组键不同,而不是免疫状态不同。

标准格式能够帮助交换这些字段,但不能替分析者决定统计单位。使用 AIRR 格式时,应区分序列标识、基因注释、支持量和其他计数字段,依据官方重排记录规范理解字段含义。把一个读段支持列改名成细胞数量,或者把缺失字段统一填零,都会让后续软件顺利读入却产生错误解释。

做多样性分析时,尤其要先选定要比较的受体范围和有效记录集合。同一样本中不同链类别具有不同分母,混合计算可能把类别组成与类别内部多样性混在一起。跨样本比较还要检查测序深度、有效支持量以及筛选后保留程度。某个样本发现的不同序列更多,并不自动证明它具有更高的真实细胞克隆多样性。

工具的优势与实际使用边界

TRUST4 的优势是能把普通转录组数据中的免疫受体信息进一步利用起来,并提供组装、注释和多个报告视图。对应的限制是,数据里没有覆盖到的受体区段不会因为运行软件而出现,表达偏倚也不会自动转化为可靠的细胞计数。需要同时审查上游证据和下游分母,才适合解释队列差异。

本次原生组件实跑说明,报告格式本身就值得单独验证。通过固定输入、只改变一种链的支持量、再单独改变过滤参数,我们观察到了彼此可区分的输出变化。相关规则还可以对照原生报告实现。这种小实验不能证明整个工具的识别准确率,却可以防止把结果表中已有的数字解释错。

实际交付时,建议同时保留原始支持量、频率、链类别、记录状态和明确的分析分母。图注应说明频率在哪个集合内计算,方法部分应记录筛选规则及克隆定义。这样,即使读者不立即复跑全部流程,也能判断一张图是在讲类别内部的受体组成,还是有依据地比较细胞群变化。

下载原创输入与原生报告组件复跑包(ZIP)。附件包含安装说明、输入生成与原生调用脚本、实际输出摘要,清楚标明只执行报告组件的范围。复跑后请按记录标识比较支持量、纳入状态和频率,不要按排序后的行号对应。

当分析扩展到批量转录组的受体重建、不同参数复核和队列汇总时,可通过云生信生物信息学分析服务器服务准备相应环境与计算资源,并统一保留上游证据和报告规则。

把知识用于当前任务

下一步可以直接开始分析

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

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