摘要: 本文提出 idrrecal 工具，针对内在无序蛋白区域（IDR）中变体效应预测器（VEP）的性能进行系统性评估与后验重校准。研究根据 IDR 的功能亚型对 VEP 性能进行分层分析，发现预测灵敏度在短线性基序和结合区域中最高，在连接区和翻译后修饰位点处最低，并揭示这一性能梯度本质上是局部进化约束程度差异的体现。在此基础上，idrrecal 构建了一个面向 IDR 的重校准层，整合 VEP 原始评分、无序注释及序列上下文，输出校准更准确的致病性预测分数。实验结果表明，重校准的核心价值在于修正预测置信度并提供更具迁移性的决策阈值，而非仅依赖亚型标签本身。工具整合了 ClinVar、AlphaMissense、ESM1b、REVEL、UniProt、ELM、dbPTM 等多源数据，支持全流程自动化复现，相关数据集与训练好的模型已托管于 Zenodo。该工作为无序区域变体致病性评估提供了更可靠的方法框架。

idrrecal：内在无序蛋白区域变异效应预测器的亚型感知重新校准与进化约束分析¶

概述¶

idrrecal 是一个面向内在无序蛋白区域（Intrinsically Disordered Regions，IDRs）的变异效应预测器（Variant Effect Predictor，VEP）性能分析与重新校准框架。IDR 是蛋白质组学研究中的重要功能区域，但由于其缺乏固定三维结构，现有 VEP 工具在该区域的预测表现参差不齐，且不同功能亚型之间存在显著差异。

该项目解决的核心问题是：现有 VEP 工具（如 AlphaMissense、ESM1b、REVEL 等）对无序区域变异的致病性预测存在系统性偏差，且这种偏差与 IDR 的具体功能亚型密切相关。idrrecal 通过对 IDR 功能亚型进行细粒度分层分析，揭示了性能梯度背后的进化约束机制，并在此基础上提供了一个事后重新校准层（post-hoc recalibration layer），使预测结果对无序残基具有更好的校准性和可迁移的操作点。

研究发现具有重要意义：VEP 敏感性在短线性基序（short linear motifs）和结合区域（binding regions）中最高，在连接子（linkers）和翻译后修饰位点（post-translational modification sites）中最低。这一梯度本质上是一种进化约束现象，而非 IDR 亚型标签本身的作用。该工具同时提供完整的可重复分析流水线，支持从原始数据下载到论文图表的全流程再现。

核心原理与功能¶

变异效应预测器的亚型分层（Subtype Stratification）¶

idrrecal 的核心分析逻辑是将 IDR 按功能亚型拆分，分别评估各类 VEP 在不同亚型下的预测性能。IDR 并非均质区域，不同功能亚型在进化压力、序列保守性和生物学功能上存在本质差异。项目整合了以下亚型来源：

ELM（Eukaryotic Linear Motif）：短线性基序数据库，覆盖功能性线性序列模式
dbPTM：翻译后修饰（Post-Translational Modification，PTM）位点注释
PhaSePro / DrLLPS / PhaSepDB：相分离（phase separation）相关区域注释
连接子区域（linkers）：连接结构域的无功能约束片段

研究结论表明，VEP 灵敏度在功能约束较强的区域（短线性基序、结合区域）显著高于功能约束较弱的区域（连接子、PTM 位点），这直接对应于各亚型所承受的进化选择压力强弱。

进化约束分析（Evolutionary Constraint Analysis）¶

该项目的关键发现之一是 VEP 性能梯度是一种进化约束现象（constraint phenomenon）。进化约束较强的区域在人群中变异频率低、序列保守性高，VEP 对这些区域的致病性区分能力较强；而约束较弱的连接子区域，其变异在进化上更能被耐受，VEP 的区分能力随之下降。

这一分析将 VEP 的局限性从"工具问题"重新定性为"生物学约束问题"，为评估和使用 VEP 提供了新的理论框架。

无序感知重新校准器（IDR-scoped Recalibrator）¶

重新校准器接受以下三类输入，输出更优校准的致病性评分：

VEP 分数：原始预测得分（如 AlphaMissense 的 pathogenicity score）
无序注释（disorder annotation）：来自 metapredict 或 IUPred3 的无序预测结果
序列上下文（sequence context）：局部氨基酸序列信息

重新校准的价值体现在两个方面：校正后的校准度（corrected calibration） 和更可迁移的操作点（more transferable operating point），而非依赖亚型标签本身进行分类。校准器底层使用 XGBoost 实现，在 Apple Silicon 平台上需额外依赖 OpenMP 运行时。

支持的 VEP 工具¶

项目集成并评估了多个主流 VEP：

VEP	来源
AlphaMissense	Google DeepMind，含非商业研究条款
ESM1b	Brandes et al.
REVEL	通过专属页面分发，不支持自动下载

数据来源体系¶

所有数据源的版本号、获取日期和 URL 在获取时自动记录于 data/raw/SOURCES.txt，保证可重复性：

ClinVar（GRCh38）：人类致病变异数据库
AlphaMissense：Google 的氨基酸错义变异致病性预测数据
ESM1b（Brandes et al.）：基于蛋白质语言模型的变异效应评分
REVEL：集成型错义变异致病性评分
UniProt 人类参考蛋白质组（UP000005640）：蛋白质序列与注释
metapredict / IUPred3：无序区域预测工具
ELM：含非商业研究条款
dbPTM：翻译后修饰位点数据库
PhaSePro、DrLLPS、PhaSepDB：相分离相关数据库

安装与使用¶

环境要求¶

项目目标 Python 版本为 3.11。

使用 uv 安装（推荐）¶

# 创建 Python 3.11 虚拟环境
uv venv --python 3.11

# 以可编辑模式安装项目及开发依赖
uv pip install -e ".[dev]"

使用 conda 安装¶

# 从环境配置文件创建 conda 环境
conda env create -f environment.yml

# 激活环境
conda activate idrrecal

Apple Silicon 特殊配置¶

在 Apple Silicon（M 系列芯片）机器上，xgboost 需要 OpenMP 运行时支持：

# 通过 Homebrew 安装 libomp
brew install libomp

关键方法与步骤¶

快速开始：重新校准示例¶

无需下载任何外部数据，直接使用项目内置示例文件进行重新校准：

# 使用 AlphaMissense 作为 VEP
# --input 指定输入变异文件（TSV 格式）
# --out 指定输出文件路径
idrrecal recalibrate --vep alphamissense \
    --input examples/example_variants.tsv \
    --out recalibrated.tsv

完整分析流水线¶

使用 make 命令驱动完整流水线，从原始数据下载到论文图表全部自动化：

# 运行完整流水线：数据获取 + 分析 + 论文生成
make all

# 仅获取和构建主数据集
make data

# 仅运行分析（基线评估、亚型基准测试、重新校准、校准度分析）
make analysis

# 仅生成图表和表格
make paper

# 运行测试套件
make test

# 运行代码风格检查
make lint

注意：完整流水线需要下载数以 GB 计的数据，并对携带变异的每个蛋白质运行无序区域预测，整体耗时较长，且对磁盘空间有较高要求。

不重新下载原始数据的复现方式¶

为降低复现门槛，处理后的数据集和训练好的重新校准器已存入 Zenodo（DOI 待提交后铸造，详见 DEPOSIT.md）。将 Zenodo 提供的制品（artifacts）放置于 data/processed/ 目录后，执行以下命令即可再现所有图表和表格：

# 仅需处理后数据，跳过原始数据下载，直接生成分析结果和论文图表
make analysis paper

REVEL 数据的手动下载¶

REVEL 通过一个阻止自动下载的专属页面分发。若自动获取失败，00_fetch_data.py 脚本会打印一次性的手动下载指引，用户按提示操作后将文件放置于指定路径即可继续流水线。

实战示例¶

场景一：对单个 VEP 输出进行无序区域重新校准¶

研究人员已通过 AlphaMissense 获得一批错义变异的致病性预测分数，现希望针对其中位于无序区域的变异进行重新校准，以获得更可靠的操作点。

# 使用内置示例快速验证工作流
idrrecal recalibrate --vep alphamissense \
    --input examples/example_variants.tsv \
    --out recalibrated.tsv

输出文件 recalibrated.tsv 包含重新校准后的致病性评分，可直接用于下游变异优先级排序或临床解读流程。

场景二：复现论文全部分析结果¶

研究人员希望独立验证论文中的所有图表和定量结论：

# 方案 A：从头开始，下载全部原始数据（需大量时间和磁盘）
make all

# 方案 B：使用 Zenodo 存档的处理后数据（推荐，速度快）
# 1. 从 Zenodo 获取制品并放置于 data/processed/
# 2. 运行分析和论文生成步骤
make analysis paper

场景三：仅运行代码质量检查¶

在对代码进行修改后，运行测试和代码检查：

# 运行测试套件
make test

# 运行代码风格和质量检查
make lint

数据流示意¶

原始数据源（ClinVar / UniProt / AlphaMissense / ...）
        ↓  make data / 00_fetch_data.py
data/raw/SOURCES.txt（版本与来源记录）
        ↓
主数据集（data/processed/）
        ↓  make analysis
基线评估 → 亚型基准测试 → 重新校准训练 → 校准度分析
        ↓  make paper
图表与表格（供论文引用）

常见问题¶

Q1：在 Apple Silicon Mac 上安装后，运行时提示 XGBoost 相关错误，如何解决？

XGBoost 在 Apple Silicon 上依赖 OpenMP 运行时（libomp），但系统默认不包含该库。需执行：

brew install libomp

安装完成后重新运行即可。若问题仍存在，请确认 Homebrew 安装路径已正确加入环境变量 DYLD_LIBRARY_PATH。[待验证]

Q2：REVEL 数据自动下载失败怎么办？

REVEL 官方通过一个阻止自动抓取的页面进行分发。当 00_fetch_data.py 检测到自动下载失败时，会在终端打印一次性的手动下载指引。按照提示访问 REVEL 官方页面手动下载文件，并将其放置于脚本指定路径后，重新运行 make data 即可继续。

Q3：完整流水线需要多少存储空间和运行时间？

原始数据来源涉及 ClinVar、UniProt 全蛋白质组、AlphaMissense 全基因组预测等大型数据库，下载量达数十 GB。此外，流水线需要对每个携带变异的蛋白质运行无序区域预测（metapredict / IUPred3），计算开销不小。具体时间和空间取决于网络环境和机器配置。[待验证具体数值] 推荐使用 Zenodo 存档的处理后数据（make analysis paper）以跳过耗时的数据获取步骤。

Q4：重新校准器对哪些 VEP 有效？--vep 参数支持哪些选项？

快速入门示例中展示了 alphamissense 选项。项目分析覆盖的 VEP 包括 AlphaMissense、ESM1b 和 REVEL。其他 VEP 选项是否受支持，请参考项目源码或文档中的参数说明。[待验证完整参数列表]

Q5：AlphaMissense 和 ELM 的许可证有何限制？

AlphaMissense 和 ELM 均携带非商业研究条款（non-commercial research terms），仅允许用于学术和非商业研究目的。项目中每个 VEP 和数据源保留其各自的上游许可证，使用前请仔细阅读相关数据源的许可协议，确保合规。

总结¶

idrrecal 系统性地回答了一个此前被忽视的核心问题：现有 VEP 工具在内在无序蛋白区域的表现为何因亚型而异。研究通过整合 ClinVar、多个 VEP 评分及 IDR 功能注释数据库，揭示了短线性基序和结合区域具有最高 VEP 敏感性，而连接子和 PTM 位点敏感性最低，且这一梯度本质上反映了进化约束强度的差异。在此基础上，idrrecal 提供的重新校准层通过融合 VEP 分数、无序注释和序列上下文，为无序残基输出校准度更优、操作点更可迁移的致病性评分。项目支持从原始数据到论文图表的全流程可重复再现，并通过 Zenodo 存档降低复现门槛，是蛋白质变异效应研究中兼顾方法创新与可重复性的实用工具。