HLA 分型表通常只有几列等位基因名称,看起来很容易交付。真正困难的地方在于判断这些名称背后的证据是否足够。一个输入较完整的样本和一个读段稀少的子集,可以给出完全相同的第一名分型,却具有不同的备选解和支持强度。如果只比较最终名称,分析过程中最值得检查的信息反而会被丢掉。
这次安装 OptiType 1.5.0,实际运行官方 NA11995 外显子示例,并从两端共同存在的读段编号中确定性选取一千对和一百对读段。完整示例与一千对子集成功导出三组候选解,第一名相同,备选解发生变化。一百对子集则在枚举后续解时出现原生程序错误,没有导出分型表。本文保留全部结果,以此讲清输入配对、目标函数、覆盖检查和失败处理。

先确认任务范围和当前软件入口
OptiType 通过整数线性规划选择能够解释读段证据的 HLA 等位基因组合,常见输出针对一类主要组织相容性基因中的 A、B、C 位点。它并不是把所有免疫相关基因都分型,也不是根据结果表直接判断免疫治疗反应。使用之前应把研究问题拆开,先明确需要哪些位点、什么分辨率、何种测序数据,再决定这个工具是否覆盖任务。
本次安装的版本具有现代命令行入口,可以直接检查依赖和执行分析。网上仍能见到围绕旧版脚本及旧解释器编写的教程,因此不能把旧命令照搬到新环境后,再把报错归因于数据。应先保存版本输出与帮助信息,确认自己读的文档对应当前程序。算法思想可参考原始研究,安装入口和参数则核对当前官方仓库。
仅安装 Python 包也不一定完成全部准备。读段比对程序和整数规划求解器属于外部依赖,需要能够被当前运行环境找到。本次通过独立环境安装,实际采用 RazerS3 比对、GLPK 求解,并运行依赖检查。依赖检查成功意味着命令可被发现,不等于已经完成分型,所以还要用实际输入验证从比对到导出结果的整条路径。
micromamba create -n optitype-demo -c conda-forge -c bioconda \
optitype=1.5.0 python=3.12
micromamba run -n optitype-demo optitype --version
micromamba run -n optitype-demo optitype check-deps
micromamba run -n optitype-demo optitype run \
-i sample_1.fastq -i sample_2.fastq --dna \
--solver glpk --threads 2 --ilp-threads 1 \
--enumerate 3 --keep-bam --prefix demo -o output
命令中的输入文件只是占位名称,需要替换为自己的文件或本文固定的官方示例。比对线程和求解器线程是不同参数,增加其中一个不意味着所有阶段都会相应加速。本次没有进行不同机器或线程数的性能比较,所以不把小示例耗时外推成全队列处理速度。保留中间比对文件的目的,是在结果异常时能回查证据,而不是仅留一张最终表。
两个 FASTQ 文件不一定逐行配对
本次使用官方仓库固定提交中的两个预筛选外显子 FASTQ。第一端有四万五千二百三十八条记录,第二端有四万三千三百九十二条记录,共同读段编号为两万五千四百一十九个。这个差异说明,它们不能按文件中同一位置直接拼成配对记录。上游筛选可能使一端被保留而另一端没有留下,分析脚本必须依据名称识别关系。
因此,制作教学子集时,我们先完整解析每条 FASTQ 的四行记录,检查名称、加号行、重复编号,再求两端编号交集。对共同编号计算固定哈希值并排序,选取前一千个和前一百个,两端都按相同编号写出。这样每个子集都包含明确配对的记录,一百对也嵌套在一千对之内,重复执行能够选到同样的数据。
这里需要交代一个实验边界。完整输入包含未在另一端出现的记录,而两个子集只来自共同编号集合,所以这个对照并非完整数据的无条件随机抽稀,也不能用于拟合通用的测序深度与准确率曲线。我们观察的是三个具体输入下的程序行为。若要系统评价最低覆盖要求,应设计多个抽样种子、不同深度、多个样本以及独立真值,并控制配对和筛选策略。
| 输入条件 | 原始记录规模 | 原生执行情况 |
|---|---|---|
| 完整官方示例 | 两端分别 45238 与 43392 条 | 成功导出三组候选 |
| 共同编号子集 | 1000 对 | 成功导出三组候选 |
| 更小共同编号子集 | 100 对 | 后续解枚举报错,无分型表 |
输入来自官方固定提交的示例目录,没有生成新的生物样本,也没有用真实临床队列验证性能。下载后校验文件内容摘要,脚本会拒绝与指定示例不一致的输入,防止同名文件更新后仍误以为是在复现同一个实验。真实项目也应保存数据来源、筛选步骤和文件摘要,这比仅记录文件名更可靠。
读段很多,为什么结果中的 Reads 小得多
完整示例的日志显示,两端分别有一千九百零九和一千八百七十六条 HLA 读段进入相应比对矩阵,随后得到一千六百八十一条配对记录、三百五十九条未配对记录以及三十二条不一致配对记录。后续还会精简重复模式和候选等位基因,构建用于优化的模型。这些阶段的数字各有含义,不能直接与原始 FASTQ 行数比较后就认定程序丢了数据。
结果列中的读段量来自所选组合在模型中覆盖的证据及其权重,而不是输入文件总记录数,也不是某个位点的平均测序深度。默认未配对权重以及一致配对规则会影响哪些证据进入优化。如果有人把这个结果列当成所有测序读段的总数,算出的“比对率”就没有明确意义。正确做法是分开记录输入数、进入比对矩阵的数、配对后证据数和最终模型覆盖量。
这种分层统计尤其适合排查输入异常。原始文件很大但可用证据很少时,应检查筛选方法、序列类型、读段名称和比对日志。若大量记录无法配对,应先查名称是否被上游工具改写,而不是立刻提高未配对权重。修改权重会改变证据的使用方式,需要说明为什么适合当前数据,并比较修改前后结果,不能仅因为某个设置能让程序产出表格就接受它。
第一名相同,备选解却已经改变
完整示例第一名的 A 位点为 A01:01 纯合,B 位点为 B08:01 与 B57:01,C 位点为 C06:02 与 C*07:01。一千对子集的第一名与之相同。但完整示例的第二、第三名主要改变 A 位点,子集的备选解主要改变 C 位点。它们提示不同输入下最容易相互替代的候选已经不同。
| 条件与候选 | 相对第一名的主要变化 | 模型覆盖 | 目标值 |
|---|---|---|---|
| 完整第一名 | 基准组合 | 1156 | 1135.192 |
| 完整第二名 | A 第二条改为 A*24:03 | 1159 | 1127.697 |
| 千对第一名 | 与完整第一名相同 | 36 | 35.352 |
| 千对第二名 | C 第二条改为 C*07:04 | 35 | 34.370 |
完整第二名覆盖的读段量比第一名还略多,却没有排在前面。这是理解目标函数的一个直接例子。程序并非只最大化覆盖条数,它还包含控制等位基因组合复杂性的项,相关参数参与纯合与杂合选择。在本次输出中,第一名与第二名的覆盖和目标值排序不同,说明把两个列当作同一个指标会误读结果。具体实现可核对官方模型代码。
目标值也不是分型正确的概率。三十五点三五二与一千一百三十五点一九二处于不同证据规模之下,不能直接据此说后者的置信度高出几十倍。备选解之间的差距同样不能直接换算成概率或置信区间。更合理的用法是在同一输入和参数条件下查看竞争组合,随后回到区分它们的位点与读段,判断是否有足够且分布合理的支持。
同样,观察到一千对读段仍给出相同第一名,不意味着所有样本只需一千对就足够。当前子集可能恰好保留了区分主要候选的读段,另一个样本、另一次抽样或不同等位基因组合可能完全不同。这里只报告一个已执行对照的事实,没有独立真值比对,也没有估计灵敏度与准确率,不能把示例成功改写成最低数据量承诺。
一百对子集失败,怎样读日志才有用
更小子集两端只有五条和三条 HLA 读段进入比对矩阵,配对后为三条一致配对记录。候选精简后仅剩一个所需等位基因,求解器完成了一次很小的整数优化,随后程序在构造后续枚举约束时报告布尔值约束错误。此时没有产生最终分型表。我们没有修改原生程序来强行通过,也没有从中间求解信息拼出一份分型结果。
这个失败至少需要从两个层面描述。直接程序原因是后续约束表达式无法被模型框架接受,日志明确给出了错误位置。数据背景则是可用证据极少、候选空间大幅缩小。两者相关,但不能仅凭这一例断言所有低覆盖数据必然触发同一错误,也不能把错误说成求解器未安装。完整示例和一千对子集已经证明相同环境能够完成流程。
排查时先定位失败阶段非常有效。如果还没进入比对就报可执行文件不存在,应处理环境。如果比对完成但有效记录锐减,应核对数据和配对。如果第一次优化已经完成,错误发生在枚举后续解,则应保存具体版本、参数、最小输入和完整日志,再对照实现或问题记录。本次选择保留失败,是因为一个未完成结果比被包装成成功的中间数字更有解释价值。
减少枚举数量可能改变程序路径,但即使由此避免某个错误,也不能补回缺失的读段证据。正式分析中应先确定最低信息要求及异常处理规则,再决定是否允许只输出一个候选。对于证据明显不足的样本,给出明确的未通过状态、失败阶段和需要补查的项目,比填入一个看似完整的等位基因组合更负责任。
从结果表回到可交付的分析记录
OptiType 的优点是目标明确,能够把多个位点的证据放入联合优化,结果结构紧凑,也便于保留备选组合。局限在于输出依赖参考等位基因集合、读段覆盖和模型假设,简单表格会掩盖输入与候选之间的复杂关系。它不负责证明新等位基因存在,也不应被当作自动覆盖所有 HLA 位点及所有分辨率的通用工具。
交付时可以保留四类材料。第一类是输入来源、读段数和配对规则。第二类是实际版本、依赖检查和命令参数。第三类是分型表、备选解及覆盖图,必要时附可回查的中间比对。第四类是失败样本清单及原因,明确哪些未完成,哪些完成但证据需要复核。四类信息对应从数据到结论的连续链条,便于别人复算,也便于之后换版本时比较变化。
查看覆盖图时,不应只看整张图是否有颜色。要关注能够区分候选的区域是否有支持,覆盖是否集中在少数位置,以及不同候选共享的读段占多大比例。整体读段量相近的样本,关键区段的覆盖也可能不同。遇到位点不一致时,应结合相应读段证据讨论,而不是仅凭某个软件名字或某个更高目标值决定谁正确。
本次实践最有价值的经验,是把“运行完成”“候选名字相同”和“证据充分”当作三个需要分别核验的条件。完整输入和千对子集满足前两个条件,但支持量与备选组合已经不同。百对子集连最终导出都没有完成。把这些差异如实保留下来,读者才能知道下一步该查环境、输入、覆盖还是候选关系。
下载原生运行驱动与实际结果摘要(ZIP)。附件说明安装版本、输入来源和复跑步骤,并保留结果解释边界。请在新的工作目录执行,逐项查看原生日志及输出状态,不能只检查外层脚本是否结束。
当 HLA 分型扩展到批量样本、多个输入策略和版本复核时,可通过云生信生物信息学分析服务器服务准备独立环境与批量任务资源,统一保留输入校验、运行日志和结果记录。
