software

SHAPEIT5 实跑指南——分块定相为何不能直接拼接,稀有位点有竖线也未必有可靠相位?

作者:发布于 2026-11-17约 11 分钟阅读
带有竖线,也可能只有一半把握。从分块方向、缓冲区到单例相位概率,逐项核验。分块方向,右块翻转 10 个样本,连接后恢复一致,Switch rate 表示方向调整比例。区间边界,读入较宽支架,输出核心区间 814 行,缓冲信息不应重复拼入最终结果。稀有位点,13 个单例杂合基因型,PP 均为 0.5,有相位表示,不等于有充分证据。

同一个样本的两条单倍型,在不同分块里可能采用相反的标签。两个文件分别看都已经定相,直接拼起来却可能在人为边界上制造一次相位切换。另一种常见误读是,稀有位点输出了竖线,就把它当成可靠的相位结果。

本文实际运行 SHAPEIT5 的常见位点定相、分块连接和稀有位点定相模块。我们用已知方向的分块作为对照,观察连接程序如何恢复方向,再用人工单例位点检查相位概率。重点是理解输出的含义、区间边界和数据核验,而不是用一个小练习评价真实人群定相准确率。

带有竖线,也可能只有一半把握。从分块方向、缓冲区到单例相位概率,逐项核验。分块方向,右块翻转 10 个样本,连接后恢复一致,Switch rate 表示方向调整比例。区间边界,读入较宽支架,输出核心区间 814 行,缓冲信息不应重复拼入最终结果。稀有位点,13 个单例杂合基因型,PP 均为 0.5,有相位表示,不等于有充分证据。
从分块方向、缓冲区到单例相位概率,逐项核验

一、安装版本与小练习的适用范围

本次于二〇二六年十一月十七日运行 SHAPEIT5 5.1.1,版本横幅记录的发布日为二〇二五年二月十九日。软件通过固定摘要的 Biocontainers 镜像安装,辅助格式转换与索引使用 BCFtools 1.25。官方源码现位于项目当前仓库,旧仓库地址可能不可用,安装时应从当前项目入口核查。

本次镜像中的可执行文件带有前缀,分别为 SHAPEIT5_phase_common、SHAPEIT5_ligate 和 SHAPEIT5_phase_rare。官方教程常用不带前缀的名称,所以遇到“命令不存在”时,应先检查安装包提供的实际程序名,而不是立即怀疑算法或输入文件。

练习生成二百四十个样本、一千二百个常见位点和二十个单例稀有位点。常见位点由人工片段拼接产生,另有一百八十个基因型被设为缺失。单例的替代等位基因计数为一,在这批二倍体样本中的频率约为零点二一个百分点。

这里的样本规模仅用于演示流程。官方对稀有位点模块的建议是用于超过两千个样本的数据,小队列可以考虑由常见位点模块完成相应工作。本文实际运行稀有模块,是为了核对接口、缓冲区和概率字段,不代表建议所有小队列采用这个分阶段方案。说明见稀有位点模块文档。

下载原创脚本与实测结果后,在 Linux 或支持 Linux 容器的环境运行即可。脚本生成全部数据,保存三个模块的实际日志,并检查输出基因型和分块连接结果。

python3 193-shapeit5/run.py output-shapeit5

二、先建立常见位点支架,不要把筛选条件当成永久标签

第一步使用常见位点模块,并设置最低频率为零点零一。人工单例低于这个门槛,因此二十个稀有位点没有进入第一步输出,剩下一千二百个常见位点。原来的一百八十个缺失基因型被补齐,所有输出基因型带有相位表示。

SHAPEIT5_phase_common \
  --input input.bcf \
  --region 20 \
  --map map.txt \
  --filter-maf 0.01 \
  --seed 193 --thread 1 \
  --output common.bcf

这里的频率门槛是为了让两类位点在练习中清楚分开,不能照搬成所有全基因组项目的推荐值。某个位点属于常见还是稀有,首先与所分析样本和统计口径有关,不能仅凭数据库里的一条频率注释确定本批数据应走哪个阶段。

频率筛选还依赖输入中的等位基因计数信息。本文在生成数据时根据实际非缺失基因型计算 AC 和 AN,并把它们写进文件。若真实项目先删去一部分样本,却继续使用旧的计数标签,过滤就可能依据错误频率进行。应在样本选择和变异处理后重新核对这些字段。

支架不只是一个文件名,它包含后续步骤要依赖的相位结构。因此需要检查样本标识、位点身份、顺序和非缺失情况。我们逐个比较原来已观测的基因型,确认二十八万七千八百二十个非缺失记录的无序等位基因组合没有改变。这个检查说明定相没有改变这些已知组合,但并不证明跨位点排列都正确。

常见模块还可以接入参考面板或已有支架,但两者的角色不同。参考面板通常提供其他样本的单倍型信息,支架则为需要定相的数据提供已知的部分相位约束。不要因为两个参数都接收变异文件,就认为可以互换。有关输入关系可查看常见位点模块说明。

三、为什么两个已定相分块不能直接连接?

设想一个样本在左侧分块中,第一条单倍型以某种顺序排列,而右侧分块把同样的两条单倍型整体交换。单看任一分块,每个位点的基因型都没错。但把它们按行拼接后,第一条单倍型在边界处突然接到另一条上,就产生了人为方向变化。

只有局部基因型正确,不足以解决这种问题。我们需要重叠区中的杂合位点,为两块之间的相对方向提供证据。如果重叠区缺乏信息,或者两块的相位估计本身不一致,连接就不能被视为简单的文本操作。

为了得到明确的答案,本次不是分别随机拟合两块,而是从同一次完整支架中切出两个重叠片段。左块覆盖到七百万位置,右块从五百万位置开始,两块共享二百零一个常见位点。随后在右块中,把前十个样本的两条单倍型全部交换。

这组构造具有已知的正确连接方式。交换没有改变任何无序基因型,却人为改变了十个样本的分块方向。我们同时保留没有交换的基准组,分别调用连接程序,检查是否能够恢复原支架中的完整有序基因型。

chunk1.bcf
chunk2_flipped.bcf
SHAPEIT5_ligate \
  --input ligated_flipped.list \
  --output ligated_flipped.bcf \
  --thread 1

文件列表需要按基因组区间排序,并且各块对应同一批样本。上面的列表是练习生成的内容,不能把名称排序与坐标排序自动画等号。真实分块常见编号十排在编号二前面的情况,应在建立列表时明确使用坐标或正确的数值顺序。

四、连接日志中的 Switch rate,不能当成真实相位错误率

基准连接和人为翻转后的连接都输出一千二百个位点。两组结果的全部有序基因型均与原始完整支架一致,说明这次已知方向的重编码被正确接回。

人为翻转组日志中的 Switch rate 为零点零四一六六六七,对应十除以二百四十,也就是约百分之四点一七的样本需要交换分块方向。这个量描述连接过程采用了多少次样本方向调整,不是“百分之四点一七的位点发生真实定相错误”。

日志还报告重叠区平均相位一致性分数为九十九。应把它理解为该连接步骤对重叠信息的概括,不能把这个数直接写成“全基因组相位准确率百分之九十九”。评价真实相位错误,需要独立真值、家系或其他合适证据,而本次只是验证已知的标签交换能否恢复。

核验项目 本次观察 能支持的结论
重叠位点 201 个 两块有共同的连接信息
人为翻转样本 10 / 240 设置了明确的方向对照
连接后位点数 1200 个 共同区域没有被重复保留
有序基因型比较 与原支架完全一致 本次重编码连接恢复成功

真实独立分块不会像这个构造一样天然具有完全一致的重叠相位。出现低一致性时,应检查重叠范围、样本顺序、基因型差异和局部定相质量。直接扩大输出范围或删除重复行,不能代替方向协调。连接工具的用途与日志定义见官方连接模块说明。

五、稀有位点的输入区间与支架区间有不同职责

稀有位点阶段使用一百万到一千一百万位置的支架信息,但只处理并输出二百万到一千万位置的核心区间。较宽的支架区间在两侧提供上下文,不能把缓冲区与最终目标区间混为一谈。

SHAPEIT5_phase_rare \
  --input input.bcf \
  --scaffold common.bcf \
  --map map.txt \
  --input-region 20:2000000-10000000 \
  --scaffold-region 20:1000000-11000000 \
  --seed 193 --thread 1 \
  --output rare.bcf

本次扫描到较宽支架范围内的一千零一个支架位点,核心区间有十三个稀有位点需要处理。日志还明确说明四个稀有位点位于缓冲区域而被排除。最终实际读取输出文件,得到八百一十四行,包括八百零一个核心常见位点和十三个稀有位点。

这个计数非常适合用于排错。扫描阶段的一千多个位点不一定都会出现在最终文件里,输入上下文和输出范围不同,数量自然不同。反过来,也不能因为日志出现某个数量,就直接把它当成最终交付行数,仍需实际读取结果核对坐标和记录数。

分块处理大数据时,常见位点支架的连接与稀有核心区间的合并承担不同工作。前者需要利用重叠区协调相位方向,后者通常已经基于一致支架处理互不重叠的核心区间。只有确认样本、头信息、坐标顺序和核心范围正确,才能按相应方案合并。

如果误把缓冲区也作为核心输出拼到一起,就可能产生重复位点。若两块核心之间存在空隙,则可能悄悄遗漏位点。建立任务清单时应检查目标区间是否完整覆盖、是否意外重叠,并在合并后再次核对唯一位点数量,而不是只检查每块是否生成了文件。

六、十三个单例都有竖线,但相位概率只有一半

本次十三个稀有位点分别只有一个杂合携带者。输出中这些基因型都使用竖线,但对应的相位概率 PP 均为零点五。日志也把它们归入单例处理,记录为十三个单例、零个由 HMM 分支解决的杂合位点。

这说明表示形式与证据强度不是一回事。程序需要写出两条单倍型上的排列,并不意味着当前数据足以确定稀有等位基因究竟应该放在哪一条上。对这些人工单例,概率的一半正是在表达缺乏区分证据。

因此,后续如果要分析复合杂合、等位基因特异表达或稀有变异共定位,不能只检查基因型分隔符。应同时考虑相位概率、家系信息、读段证据及相关方法的适用条件。一个低置信度相位若被当成确定事实使用,可能把统计推断中的不确定性隐藏到下游结论中。

本次没有检验家系辅助定相,也没有使用长读段证据。真实项目若加入这些约束,应保证各阶段使用同一份关系信息,并检查其样本标识及方向约定。不能在前一步赋予父母来源意义,后一步连接时又允许任意交换两条单倍型。

七、可复现记录应包括线程数,而不仅是随机种子

探索过程中使用两个线程时,程序明确提示,仅指定随机种子不能保证多线程运行完全复现。最终附件中的正式核验统一使用单线程,并保留固定输入种子和算法种子。这样既能减少教学对照中的额外变化,也能让读者更容易定位差异来源。

这不意味着实际大型项目都应改成单线程。更合理的做法是根据任务选择并行方式,同时完整记录软件构建、线程设置、输入版本与区间清单。对要求逐项复核的小例子,可以优先减少并行的不确定性。对生产规模分析,则应明确哪些输出要求完全一致,哪些允许数值或相位等价。

本次最有价值的经验不是得到了一份带竖线的文件,而是把不同层次的验证分开了。常见位点检查已观测基因型是否保持,连接阶段检查方向是否协调,稀有阶段检查核心区间和概率字段。每一步都有对应证据,才能知道完整流程真正完成了什么。

需要把分块任务、支架版本和核验记录长期保留下来时,可通过云生信生物信息学分析环境服务建立可复用的定相分析流程。

把知识用于当前任务

下一步可以直接开始分析

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

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