HiCExplorer 实跑指南——矩阵权重、校正与 TAD 窗口，怎样判断边界变化来自哪里

同一份接触矩阵，转换格式以后数值变了，换一组窗口以后边界分数变了，最后却仍然得到相同的两个边界。遇到这样的结果，应该认为分析稳定，还是认为参数没有生效？回答之前，要先分清原始接触、校正矩阵、分离分数和离散边界分别代表什么。把这些层次混在一起，最容易产生一种错觉，只要软件输出了区域文件，就已经证明了染色质结构。

本文实际安装并运行 HiCExplorer 4.0.0，使用自己编写的一百二十分箱接触矩阵，依次检查格式转换、矩阵平衡、窗口调整和缓存复用。输入完全是人为设计的数据，没有真实细胞，没有测序噪声，也没有重复样本。本次运行能够说明程序怎样处理这些输入，不能评价真实样本中的拓扑结构域识别准确率，更不能把命中的边界当作新的生物学发现。

一、先决定你要比较哪一层结果

接触矩阵记录分箱之间的联系，行列覆盖不均衡会影响图像明暗。矩阵平衡试图处理其中一部分系统性差异，分离分数则观察某个位置两侧的接触关系。边界识别还会增加局部极小值、差异幅度和统计门槛等条件。因此，校正后行和接近，并不意味着每个局部区域的接触模式相同。边界数量相同，也不意味着每个位置的分数相同。

实际项目中，我建议先写下比较对象。如果问题是处理前后接触分布有没有改变，就检查原始与校正矩阵。如果问题是某个候选边界是否变弱，就比较相同窗口下的分离分数及附近覆盖。如果问题是不同条件的结构域数量是否不同，还要控制有效接触数量、分辨率、掩蔽区域和调用门槛。直接比较两个区域文件的行数，跳过了中间几层证据。

HiCExplorer 的实用之处在于这些步骤都有独立入口，既可以组织成流程，也可以拆开检查。代价是操作者必须记住每个文件经过了哪些变换。一个文件名里的“校正”二字不够，至少要记录输入分辨率、权重列、校正方法、过滤条件以及是否又做了其他变换。

二、用一个可以手算局部结果的矩阵开始

本次构造一条长十二万碱基的虚拟染色体，按一千碱基分成一百二十个分箱。每四十个分箱设为一个人工接触增强区，区内联系乘以八，区间联系不乘。再加入随距离衰减的基础值，以及按固定模式重复的分箱偏差。这样既有可预期的区块位置，也有需要处理的行列覆盖差异。

这是一种排查方法，而不是对真实染色质的完整模拟。人为增强区之间没有真实细胞群体异质性，覆盖偏差也只是一个简单乘法因子。它的价值在于，当输出不符合预期时，可以直接追溯到某一对分箱，不必同时猜测比对、多重定位、实验批次和重复序列的影响。

我们还在原始文件中存入人为权重，值是分箱偏差的倒数。这列权重仅用于检验转换行为，并不是软件从真实数据估计的结果。原始计数和人为权重同时存在，正好可以回答一个常被忽略的问题，转换命令默认读取的到底是哪一种数值。

固定环境和完整生成脚本放在实跑复现包。下面的命令展示关键步骤，复现包里的运行器会准备输入，并在隔离的容器目录内执行。

IMAGE=quay.io/biocontainers/hicexplorer@sha256:868b27997ec40d1f656d472d4ed6a914b2145fd7decf1dc75af32f6b8e9e0cca
docker pull "$IMAGE"
python3 run.py ./hicexplorer_practice

三、格式转换可能同时应用权重

我们分别运行一次默认转换和一次显式读取原始值的转换。两次输出格式都是层次化矩阵文件，但第零号与第一号分箱之间的数值，前者为四百八十，后者为九百六十。这个变化与人为权重相乘的结果完全一致，说明本次默认转换确实应用了已有权重。

hicConvertFormat -m toy.cool \
  --inputFormat cool --outputFormat h5 \
  -o weighted.h5

hicConvertFormat -m toy.cool \
  --inputFormat cool --outputFormat h5 \
  --load_raw_values -o raw.h5

表中总和是展开后的完整对称矩阵求和，非对角线联系在两个方向出现，不能直接当作独立接触分子总数。这里使用它只是检查同一表示方式下的数值变化，真正比较有效接触量时，应回到原始接触列表或按存储约定统计。

这一步的经验很明确，格式转换前先看权重列，转换后抽查几个非零单元。已经应用过权重的矩阵如果又被当作原始计数送去校正，分析的起点就变了。软件不会理解你的文件命名意图，只会按输入结构和参数执行。默认权重列、原始读取选项及权重的应用方式见格式转换官方说明。

四、校正方法不同，同名过滤参数未必生效

接下来对明确保留原始值的矩阵执行 KR 平衡。校正前，各行数值总和的变异系数约为零点四六二。校正后约为二点二四乘十的负八次方，各行总和都接近一万九千零五十三点八。这个结果说明本例的行和均衡目标得到了满足，并不说明所有实验偏差都已消失。

hicCorrectMatrix correct \
  --matrix raw.h5 --outFileName kr.h5 \
  --correctionMethod KR --threads 1

我们还做了一个故意设置极端过滤阈值的对照，仍使用 KR 方法，额外传入 --filterThreshold 100 101。两次输出逐元素最大差异为零。原因不是这些阈值“恰好没过滤掉任何异常点”，而是该参数在本次版本中适用于 ICE 校正。把另一种算法的参数放进命令，不等于已经完成那项过滤。

这类问题适合在正式分析前用小输入检查。先设置一个应该明显影响结果的极端条件，再比较掩蔽数量或输出矩阵。如果完全没有变化，先核对参数适用范围，而不是立即解释为数据非常稳定。两种校正方法及专用过滤参数可以对照官方校正工具说明。

行和平衡也有使用前提。覆盖极低的分箱即使被放大，也不会凭空增加信息。缺失区、组装空洞和不可靠分箱应该有清楚的处理记录。对于拷贝数改变明显或跨样本深度不均的研究，更不能把“已经校正”视为消除所有可比性问题的证明。

五、改变窗口后，先看分数，再看边界数量

第一次调用使用最小窗口三千碱基、最大窗口九千碱基，第二次使用六千至一万八千碱基。两次都采用相同的统计门槛、差异幅度门槛和最小边界间距。窗口是在观察尺度上作调整，不是改变输入矩阵的分箱大小。

hicFindTADs -m kr.h5 --outPrefix small \
  --minDepth 3000 --maxDepth 9000 --step 1000 \
  --correctForMultipleTesting fdr \
  --thresholdComparisons 0.05 --delta 0.01 \
  --minBoundaryDistance 4000 -p 1

两组重新计算的分数明显不同，但两个主要边界仍位于人工区块连接处。因此，“边界没变”只能说明本例这些离散边界对这两组窗口较稳定，不能说窗口没有影响结果。若研究关注的是边界强度，分数变化本身就不能略过。

另一个需要注意的细节是，人工输入有三个增强区，区域文件却只给出四万至八万碱基之间的一个区间。输出规则根据相邻保留边界形成区域，不会为了对应我们设计的区块数，自动把染色体两端也补成完整区域。拿输出行数去计算“找回了几个真实结构域”，在这个例子里从定义上就不合适。

边界文件把四万附近报告为三万九千五百至四万零五百的区间，区域文件则使用四万作为连接坐标。阅读结果时要保留区间和分辨率信息，避免把文件的起点误称为精确到单碱基的物理边界。官方对输出类型和边界判定步骤的说明见边界识别文档。

六、复用缓存时，命令里写了新窗口也可能没有重算

第三次调用复用第一组的分离分数缓存，同时在命令中写入第二组窗口参数。得到的仍是第一组分数，而不是第二组重新计算的结果。这个操作适合调整基于同一分数的筛选门槛，不能当作新窗口实验。

缓存读写带来约百万分之一以内的浮点差异，因此复现脚本比较数值容差及边界坐标，没有要求文本文件每一个字符完全相同。这也是实际核验时应区分的两件事，数值上的同一结果不一定具有逐字节一致的文本表示，反过来，文件名变化也不证明计算内容变化。

如果要改变观察尺度，应使用新的输出前缀重新计算分数。若只是比较不同显著性门槛或差异幅度门槛，可以复用同一缓存，并在记录中明确缓存来源。否则一个看起来包含新参数的命令会留下错误印象，让后续分析者以为所有组合都独立计算过。

我们还把最小窗口设为两千碱基，程序明确报错，要求至少达到当前分箱大小的三倍。这个错误是在提醒你统计窗口的信息量不足，不能靠修改文件名或增加线程解决。参数扫描应先根据分辨率排除不合法组合，再讨论科学问题需要什么尺度。

七、真正比较样本时，怎样把这套检查用起来

首先选定一块有足够接触覆盖、没有明显缺口的区域，把原始计数图、校正后图、连续分数曲线和边界位置放在同一个坐标系里。若某条边界只在覆盖骤降处出现，要先检查输入质量。若矩阵图看不出相应结构，而边界随微小阈值变化大量跳动，也应该降低对离散调用的信任程度。

其次保留一张参数和文件关系表，写清楚哪些结果重新计算了分数，哪些只是复用了缓存。表中最好同时记录有效分箱数和掩蔽区域。否则两个样本都写“一万碱基分辨率”，实际可用位置却可能不同，区域交并比会把技术缺失误算成结构变化。

最后，重复样本之间的稳定性应先于跨条件结论。同一条件内部都不稳定的边界，没有理由仅凭两个合并矩阵的一次调用就认定发生了改变。连续分数、接触覆盖和重复一致性可以帮助筛出值得进一步验证的位置，离散区域文件只是其中一个摘要。

比较边界位置时还应提前规定允许偏移的范围。例如两次调用在相邻分箱中选中了极小值，可能仍描述同一个宽边界。若只按坐标完全相等来统计重叠，会把这种小位移算成一条边界消失和另一条边界新增。允许偏移的范围应与分辨率及研究问题一致，在看到比较结果之前确定。还应单独列出一方缺少有效覆盖的位置，让真正可比较的边界拥有明确分母。这比事后挑一个能提高一致性的距离阈值更有解释力。

HiCExplorer 的优势是处理步骤清楚、输出可拆开检查，适合把矩阵处理与边界分析串起来。局限也正来自这种灵活性，输入是否已校正、不同方法的过滤范围、缓存对应的尺度，都需要操作者管理。本次最有价值的经验不是某组窗口“最好”，而是用逐元素核对和对照参数，确认每一步到底改变了什么。

当这些输入与参数已经核清、需要扩展到多个样本和多组分辨率时，可了解云生信生物信息学分析环境与算力服务，把经过验证的流程用于后续批量分析。