genomorph：调控变异效应机制的优化传输指纹¶

概述¶

genomorph 是一个基于最优传输（Optimal Transport）理论的 Python 工具，用于为调控变异（regulatory variant）的效应机制生成固定维度的指纹（fingerprint）。它本身不预测变异效应，也不捆绑任何模型权重，而是作为一个表征层 + 评估层，架设在任意序列到功能模型（sequence-to-function model）之上。支持的模型后端包括 Borzoi、Enformer、AlphaGenome 等，全部计算仅在 CPU 上进行，许可证为 Apache-2.0。

当前的 pre-alpha 版本（v0.1.0a）专注于从模型输出的 REF（参考）和 ALT（替代）覆盖度曲线 中提取形状（shape） 与符号化质量（signed mass） 信息。传统做法会将这些曲线压缩成单一的效应大小标量（per-track scalar），而 genomorph 保留了坐标轴上的分布差异，能够区分机制完全不同的变异效应——例如峰的平移（shift）、信号丢失（loss）、信号获得（gain） 以及峰的展宽（broadening）。

在受控的合成基准测试中，genomorph 指纹能将变异按已知机制聚类，其调整兰德指数（Adjusted Rand Index, ARI）显著高于同模型输出的标准标量摘要（即 per-modality 的 L2 大小，下称“vep-scalar”）。在幅度被均衡化、标量完全无信息的“匹配”机制下，指纹 ARI 达到 0.57（vep-scalar 仅 0.02）；在保留自然幅度的“自然”机制下，指纹 ARI 高达 0.95（vep-scalar 为 0.23）。该声明由自举法（bootstrap）生成的 95% 置信区间支持，并在 5 个随机种子上均成立。

genomorph 适用于任何需要深入理解变异如何改变调控信号形状的研究场景，尤其适合宏基因组功能注释、表达数量性状位点（eQTL）机制探索等任务。它轻量、后端无关、可复现，并附带了在 eQTL 目录子集上运行的完整评估框架。

核心知识点¶

1. 从标量到形状：为什么需要形状指纹？¶

现代序列到功能模型（如 Enformer、Borzoi）可针对一个序列变异，为每种实验测定（assay）预测出两条覆盖度曲线——一条针对参考等位基因（REF），另一条针对替代等位基因（ALT）。领域内最常见的信息压缩方式是对每条曲线取某种范数（如 L2 距离），得到一个效应该测定上的标量效应大小。然而，这种标量化丢弃了所有空间分布信息：一个峰平移 100 bp 与一个峰完全消失、或者一个峰显著加宽，在 L2 大小上可能完全相同，但它们的生物学含义截然不同。

genomorph 的核心思想是将 REF 和 ALT 的差异视为定义在基因组坐标上的一个带符号测度（signed measure），然后利用最优传输中的 Wasserstein-1 距离 捕捉分布形状的变化。具体来说，它将变异效应分解为两个正交的分量：

• 形状项（shape term）：对质量归一化后的 REF 和 ALT 曲线计算 1 维 Wasserstein-1 距离（Earth Mover’s Distance）。该距离度量了概率质量重新分配的最小“总工作量”，完全独立于总质量的增减。
• 符号化质量项（signed mass term）：两条曲线总信号量的净变化，即 ALT 总和减去 REF 总和。

此外，genomorph 还提取差异的增益-损失空间分离度（通过对 REF−ALT 差异进行 Jordan 分解得到正部与负部，并计算它们重心之间的位移）以及支撑宽度比（support width ratio）。这四个属性共同构成一个固定维度的特征向量，称为指纹。

这种分解带来的优势是机制可解释性：若峰发生平移，形状项将显著大于零，而质量项接近零；若发生纯损失，质量项为负且绝对值大，形状项取决于丢失质量的分布；若峰展宽，支撑宽度比增大，形状项也会响应。指纹因此能够区分那些被标量混淆的效应模式。

2. 最优传输与 Wasserstein-1 距离¶

Wasserstein-1 距离（也称为 Earth Mover's Distance）衡量的是将一个分布变换为另一个分布所需移动的“概率质量”乘以移动距离的平均最小值。在 1 维基因组坐标上，该距离具有闭式解，可以通过排序后累积分布函数之差的积分高效计算。genomorph 使用 POT（Python Optimal Transport）库实现，仅需 CPU 资源，不依赖 GPU。

通过对 REF 和 ALT 曲线先做质量归一化（除以各自总质量），我们移除了总强度的影响，使 Wasserstein-1 距离纯粹反映分布形状的差异。而总质量的增减被单独捕获为符号化质量项。这种解耦设计确保了形状指纹不会受测序深度或表达整体水平的干扰。

3. 指纹构成与对比基准¶

genomorph 提取的固定维度特征包含以下字段（归一化到统一尺度后用于聚类或嵌入分析）：

这些值经过滑窗聚合（所有测定类型）得到最终的指纹向量，可以直接输入聚类算法。

为证明指纹比标量摘要更优，genomorph 设定了一个强控制基线（raw per-bin delta）：直接将两条曲线的逐个分箱差异作为特征，此时没有丢弃任何空间信息。即便如此，指纹在合成数据上的聚类 ARI 仍然更高，证明少量的几何特征比高维原始差异更能抓住机制的本质。

4. 合成基准实验设计¶

该工具的核心声明建立在合成基准之上，但力求公平和无偏：

• 后端统一：所有比较使用同一后端（Borzoi/Enformer/mock）输出的相同 REF/ALT 曲线。
• 机制明确的合成变异：合成变异被构造为具有单一已知机制，如局部峰平移、纯损失、纯增益、强度衰减、展宽等。
• 两种幅度设定：
• 匹配幅度（matched）：人为均衡不同机制产生的总效应大小，使标量摘要完全无信息——此设定专门隔离形状的贡献。
• 自然幅度（natural）：保留模型自然产生的幅度差异，模拟真实情况。
• 指标与统计检验：使用调整兰德指数（ARI）衡量指纹或标量对已知机制标签的聚类一致性；通过配对自举法计算 ARI(fingerprint) − ARI(vep-scalar) 的 95% 置信区间。若区间下限大于零，即认为形状信息显著提升了机制分离能力。

实验在 240 个合成变异、5 个不同随机种子上重复。结果一致地显示指纹 ARI 显著优于标量，且 MAD 缩放（中位数绝对偏差归一化）在全部种子上对指纹有益。

5. 真实数据评估与可复现性¶

genomorph 内嵌了一个来自 eQTL 目录（Kerimov et al.）的 167 个变异的子集，配有假设的机制标签（如“增强子丢失”、“剪接获得”等）。该子集允许用户使用任意后端生成指纹并进行聚类评估。由于运行真实后端（如 Borzoi 或 Enformer）需要下载权重文件和参考基因组 hg38 FASTA，这在持续集成（CI）环境中难以自动化，因此默认 CI 流程仅使用 mock 后端进行布线烟雾测试（wiring smoke），此时指纹与 ARI 无实际意义并明确标注。用户只需本地配置权重文件即可复现真正的真实数据 ARI，评估代码一键运行：

genomorph eval-real --backend enformer --genome-fasta /path/hg38.fa

该设计保证了结果的完全可复现性，同时尊重了后端权重的许可与分发限制。

6. 未声明的内容与局限¶

• 无因果证明，无临床应用：genomorph 指纹仅反映预测效应的几何特性，不等同于因果调控机制，也不应用于临床或诊断决策。
• 合成数据上的明星数字：标题中的 ARI 提升是在合成基准上测得，真实数据上的表现取决于后端模型对机制的保真度。真实标签子集用于展示框架，但其 ARI 取决于所使用的模型。
• 不捆绑权重与输出：工具绝不重新分发任何后端模型的参数或预测结果。
• AlphaGenome 后端需非商业许可。

代码实操¶

安装¶

genomorph 提供基础版和带后端的扩展安装方式：

# 核心依赖：numpy, scipy, scikit-learn, POT
pip install genomorph

# 安装 Borzoi 后端（权重许可 MIT）
pip install "genomorph[borzoi]"

# 安装 Enformer 后端（Apache-2.0）
pip install "genomorph[enformer]"

快速开始：命令行接口¶

# 复现领先的合成基准测试（匹配幅度）
genomorph benchmark --regime matched --out results.json

# 使用 mock 后端为单个变体生成指纹（无需权重，仅用于演示）
genomorph fingerprint chr1_108004887_G_T --backend mock

# 真实 eQTL 子集评估：
#   mock 后端 -> 布线烟雾测试（快速，ARI 标记为无意义）
genomorph eval-real --backend mock

#   enformer 后端 -> 真正的评估（需准备 hg38 FASTA 文件）
genomorph eval-real --backend enformer --genome-fasta /path/to/hg38.fa

Python API 用法¶

以下代码演示如何获取变异效应并提取指纹：

import genomorph as gm

# 获取所需后端实例，选项："mock"、"borzoi"、"enformer"
backend = gm.get_backend("enformer")

# 预测变异效应，返回 VariantEffect 对象（包含 REF 和 ALT 覆盖数据）
variant_str = "chr1_108004887_G_T"
effect = backend.predict(variant_str)

# 根据后端提供的测定模态创建指纹提取器
extractor = gm.FingerprintExtractor(backend.modalities)

# 提取固定维度指纹
fingerprint_vector = extractor.transform_one(effect)

print(fingerprint_vector)  # 形状 (n_features,)

对于一整批变异，可以使用 transform 方法直接获得特征矩阵，用于后续聚类或降维可视化。

可视化（v0.1.0a 附带）¶

genomorph 还提供基于 Oklab 色彩空间的低维嵌入可视化，可直观观察不同机制的聚类结构。调用方式如下：

import genomorph.viz as gv
# 假设有一组指纹矩阵 fingerprints 和对应的机制标签 labels
embedding = gv.embed_oklab(fingerprints)
gv.plot_embedding(embedding, labels, title="Mechanisms clustered by genomorph")

常见问题¶

1. 为什么 CI 中的真实数据 ARI 是“无意义的”？¶

为了在法律和技术上简化，genomorph CI 不能下载受许可保护的模型权重和参考基因组。因此真实数据评估回退到 mock 后端，它返回随机曲线，其聚类 ARI 当然接近随机水平。这一运行仅用于确保代码逻辑正确、无导入错误。有意义的真实数据 ARI 需要用户在本地配置后端权重后重新运行，脚本相同。

2. 我可以添加自己的序列到功能模型后端吗？¶

可以。genomorph 的后端接口非常简单：只需实现一个返回 VariantEffect 对象的方法，该对象包含 REF 和 ALT 在每个测定上的覆盖度曲线。参考现有后端的实现（如 genomorph/backends/mock.py），然后注册即可使用。工具不假设任何特定模型架构。

3. 指纹的维度是多少？会随着测定类型数量改变吗？¶

指纹维度固定，不依赖于输入测定的种类数。genomorph 对所有测定提取上述几何特征后，通过均值或中位数等操作聚合为全局特征向量，因此无论输入多少个测定通道，输出的指纹长度始终相同。这使得跨研究和跨模型的比较成为可能。

4. Wasserstein 距离的计算对坐标轴敏感吗？¶

是的，因为它直接基于基因组位置计算。genomorph 内部使用统一的坐标标准化（如碱基对位移），并假设所有输入曲线的分箱对齐。如果不同模型的分箱策略不同，工具会自动重采样到统一网格。

5. 形状指纹能应用于非调控变异（如编码区变异）吗？¶

该工具的设计出发点基于调控信号的连续覆盖曲线。若编码变异也能产生类似的 REF/ALT 曲线（例如通过功能预测模型输出某种分值沿蛋白质位置的分布），理论上可以应用，但目前未经过验证。genomorph 的未来版本可能会扩展对剪接机制和接触图拓扑的支持。

6. 是否存在计算性能瓶颈？¶

核心计算走 POT 库的 EMD 求解器，1 维情况极快。在仅 CPU 环境下，单变异提取指纹耗时数毫秒，对数千变异的批量处理完全可行。真实后端的主要瓶颈在于模型推理本身，而非 genomorph 的指纹提取。

速查表¶

genomorph 通过低维的几何特征将序列到功能模型的输出转化为可比较、可解释的调控效应表示。它不取代下游效应预测，而是为研究者提供一种揭示突变“如何”改变调控格局而非仅仅“有多大”的镜头。随着未来版本加入剪接机制、Gromov–Wasserstein 跨模态比较以及拓扑特征，这一表示体系将更加完备。