tooluniverse-protein-sae-variant-interpretation

蛋白质 SAE 变体解读

通过比较 ESMC-6B 蛋白质语言模型的参考序列与突变序列的稀疏自编码器（SAE）特征激活，解读单个错义变体。SAE 特征是模型隐藏状态中可解释的潜在维度——许多特征会在具有生物学意义的模式上激活（活性位点、配体结合口袋、PTM 序列基序、结构基序）。

---

何时使用此技能

适用于用户：

• 询问“为什么变体 X（错义变体）会导致功能丧失？”并需要超出致病性评分的机制性解释
• 已有 AlphaMissense / ClinVar 判定为“有害”的变体，想了解哪种功能特征受损（催化？结合？PTM 位点？结构？）
• 想比较特定残基处参考蛋白与突变蛋白的表示
• 想了解为何一个结构变化不明显的变更（单个 AA）会产生重大功能影响

不适用于（请改用其他技能）：

• ACMG 致病性分类 → tooluniverse-variant-interpretation
• 调控 / 非编码变体 → tooluniverse-variant-to-mechanism
• 不涉及机制的变体与疾病关联 → tooluniverse-gene-disease-association
• 癌症特异性变体解读 → tooluniverse-cancer-variant-interpretation

---

必需输入

输入	格式	示例
蛋白质标识符	UniProt 登录号或 HGNC 基因符号	P04637 或 TP53
变体	单字母格式：{ref_aa}{position_1idx}{alt_aa}	R175H

可选：

• 窗口半径（默认值为 8）：要分析的突变周围残基范围
• 参考蛋白质序列（若已知，可跳过 UniProt 查询）

---

前置条件

• ESM_API_KEY 环境变量，包含有效的 EvolutionaryScale Forge 令牌（https://forge.evolutionaryscale.ai）
• 支持 SAE 的 esm package：

  pip install 'esm @ git+https://github.com/evolutionaryscale/esm@ee891c52'
  

  PyPI 版本的 esm 尚未包含 SAEConfig。请从上游功能分支安装。

许可证说明：Forge 的 SAE 输出受 Cambrian Inference Clickthrough License 约束——仅限非商业 / 学术研究用途，除非另有商业协议。

---

工作流（5 个步骤）

步骤 1：将基因解析为 UniProt 登录号（如有需要）

如果用户提供了基因符号，请解析为经过审阅的人类登录号：

UniProt_search(
    query="gene:TP53 AND organism_id:9606 AND reviewed:true",
    fields=["accession", "gene_names", "protein_name"],
)
# → returns accession P04637 as the canonical reviewed human TP53

步骤 2：获取规范参考序列

UniProt_get_sequence_by_accession(accession="P04637")
# → returns the canonical isoform 1 sequence (393 AA for TP53)

步骤 3：验证参考残基并构建突变序列

解析变体字符串（例如 R175H）：

• ref_aa = "R"、position = 175（从 1 开始计数）、alt_aa = "H"
• 验证 ref_sequence[174] == "R"（Python 从 0 开始计数，位置从 1 开始计数）
• 构建突变序列：mutant_sequence = ref_sequence[:174] + "H" + ref_sequence[175:]

如果参考残基不匹配，返回明确错误——不要默默突变错误的位置。

快速路径（推荐用于变体分析）：组合工具

对于标准的变体解读用例，请根据所需信息量使用以下两个组合工具之一：

最完整的一次调用——扰动 + 每个特征的生物学类别标签 + 机制摘要：

ESM_explain_variant_mechanism(
    sequence=ref_sequence,
    position=175, ref_aa="R", alt_aa="H",
    window=8,
    top_k_features=5,       # describe top 5 lost + top 5 gained
)
# data["mechanism_summary"] e.g. "Disrupted feature categories (lost): catalytic=2, ligand-binding=1"
# data["lost_feature_categories"] / ["gained_feature_categories"] — category counts
# data["top_features_lost"] / ["top_features_gained"] — per-feature delta + category + confidence

这是变体机制报告的推荐默认选项——可省去串联调用 ESM_score_variant_sae_disruption 和 N 次 ESM_describe_sae_feature。将 include_descriptions=false 设为跳过标签（仅需调用 Forge 2 次），适用于只需要差值的情况。

仅原始差值（无类别标签、不调用描述工具——速度更快）：

ESM_score_variant_sae_disruption(
    sequence=ref_sequence,
    position=175, ref_aa="R", alt_aa="H",
    window=8, top_k_features=10,
)
# → returns top_features_lost + top_features_gained ranked by |delta|
#   plus ref / mut activation sums per feature

如果给定位置的序列中 ref_aa 不匹配，这两个工具都会返回明确错误（你提供了错误的异构体 / 错误标注了变体）。下文较长的路径用于检查原始的逐残基特征。

一次处理多个变体（例如，对残基 175 进行饱和突变——全部 19 种替换）：

alts = "ACDEFGHIKLMNPQRSTVWY".replace("R", "")
variants = [{"position": 175, "ref_aa": "R", "alt_aa": a} for a in alts]
ESM_score_variant_sae_batch(sequence=ref_sequence, variants=variants, top_k_features=5)
# 1 + 19 = 20 Forge calls, not 38

第 4 步（长路径）：获取参考序列和突变序列的 SAE 特征

ref_features = ESM_get_sae_features(
    sequence=ref_sequence,
    position=175,          # 1-indexed mutation position
    window=8,              # +/- 8 residues = 17-residue window
    top_k_per_residue=64,  # full sparsity (k=64 is the SAE's actual k)
)

mut_features = ESM_get_sae_features(
    sequence=mutant_sequence,
    position=175,
    window=8,
    top_k_per_residue=64,
)

每次调用都会返回一个列表，其中包含窗口内各残基的 {residue_idx_1based, active_features: [{feature_id, activation}]}。典型延迟：每次调用约 1–3 秒（总计约 2–6 秒）。Forge 费用：2 个 credits（每次调用 1 个）。

第 5 步：计算每个特征的激活变化量

汇总窗口内新增／丢失的特征：

# Build per-feature activation arrays across the window
def feature_to_window_sum(features_response):
    sums = {}  # feature_id -> sum of activations across all residues in window
    for residue in features_response["data"]["activations"]:
        for f in residue["active_features"]:
            sums[f["feature_id"]] = sums.get(f["feature_id"], 0.0) + f["activation"]
    return sums

ref_sums = feature_to_window_sum(ref_features)
mut_sums = feature_to_window_sum(mut_features)

# Delta = mut - ref. Positive = gained on mutation. Negative = lost.
all_features = set(ref_sums) | set(mut_sums)
deltas = {
    f: mut_sums.get(f, 0.0) - ref_sums.get(f, 0.0)
    for f in all_features
}

top_lost = sorted(deltas.items(), key=lambda x: x[1])[:10]       # most negative
top_gained = sorted(deltas.items(), key=lambda x: -x[1])[:5]     # most positive

---

解读表

这 16,384 个 SAE 特征根据 UniRef90 激活模式归为约 6 种生物学类型。根据特征的主要类别进行解读：

类别	生物学含义	常检测到的变体类型
催化功能	在酶活性位点上或附近的残基处激活	破坏酶活性的变体（激酶、水解酶、转移酶）
配体结合位点	在接触小分子／离子／核苷酸配体的残基处激活	破坏药物结合、ATP/GTP 结合、金属配位、DNA/RNA 结合的变体
翻译后修饰（PTM）	在磷酸化位点、糖基化序列、泛素化位点、乙酰化位点处激活	破坏磷酸化调控、N-糖基化、泛素介导降解的变体
结构域／基序	在经典结构域（锌指、亮氨酸拉链、EF-hand 等）处激活	破坏结构域内三级折叠的变体
结构稳定性	在对局部折叠至关重要的残基处激活	使蛋白质不稳定的变体 → 折叠 LoF
二级结构／表面	在 α 螺旋、β 链、溶剂暴露残基处激活	特异性较低；机制信号较弱

突变导致 SAE 特征丢失时 → 相关生物学功能可能受到破坏。
突变导致 SAE 特征新增时 → 突变可能引入了非天然信号（通常与无序／替代折叠有关）。

使用 ESM_describe_sae_feature(feature_id=...) 查询任意特定 feature_id 的生物学类别。首次查询某个特征时速度较慢（约 30 秒，约 10 个 Forge credits，因为该工具会在 10 个蛋白质组成的标注面板上运行 SAE，并检查 UniProt 注释）；之后对同一特征的查询会命中本地缓存，立即返回。

---

需要如实说明的局限性

1. SAE 特征 ≠ 真实功能。SAE 特征是根据序列模式学习得到的。“Feature 16076 看起来像是 N-糖基化检测器”是根据该特征在 UniRef90 中的表现提出的假设，并非针对单个残基的功能注释。请将其视为证据，而非证明。
2. 仅覆盖 ±8 个残基的窗口。该窗口覆盖局部影响（活性位点破坏、基序破坏），不涵盖远程变构效应、二聚化界面效应，或会改变远离突变位置的特征的结构域间重排。
3. 特征标签覆盖不完整。部分 16,384 个特征尚未得到良好分类——它们会在不同位置激活，或呈现不明确的模式。对于未分类的特征，SAE 变化量仍有参考价值（说明发生了变化），但生物学解读的可靠性较低。
4. 仅支持单一异构体。使用 UniProt 规范序列。如果变体位于非规范异构体中，结果可能不适用。
5. 仅支持 6b SAE。目前 TU 支持 esmc-6b-2024-12_k64_codebook16384_layer60 SAE。较小的 600m SAE 虽然存在，但尚未根据源代码库中的 LoF 基准进行验证。
6. Forge API 不得用于商业用途。未经 EvolutionaryScale 另行许可，不得将此技能的输出用于商业用途。

---

交叉验证模式（推荐）

单独使用基于 SAE 的分析可能会产生误导。对于高风险解读，请结合结构和群体证据进行交叉验证：

层级	工具	可确认的问题
群体频率	gnomad_get_variant / gnomad_search_variants	该变异是否罕见？（LoF 候选变异通常较罕见或不存在）
致病性预测	AlphaMissense_get_variant_score	独立的 ML 预测器是否也认为它有害？
临床证据	ClinVar_search_variants + ClinVar_get_variant_details	该变异是否已被整理并标注临床意义？
结构背景	alphafold_get_prediction（返回每个残基的 pLDDT）	突变残基是否位于折叠良好的区域（pLDDT > 70）？
功能注释	UniProt_get_disease_variants_by_accession、UniProt_get_function_by_accession	突变残基是否位于已知的催化位点、结合位点或 PTM 位点？

如果 3 个或更多层级都认为该变异有害，那么 SAE 特征分析就是机制解释层：“AlphaMissense 认为它有害，gnomAD 确认它在群体中不存在，SAE 显示催化特征已丢失 → 这是一个催化功能丧失变异。”

---

报告格式

完成工作流后，请按以下格式总结：

Variant: {VARIANT_ID}  (e.g. P04637_R175H = TP53 R175H)
Protein: {gene} ({uniprot_accession})

Top features LOST at position {position} ± {window}:
  - Feature {id}: activation Δ = {delta:.2f}  (category: {category})
    {one-line biological summary}
  ...

Top features GAINED at position {position} ± {window}:
  - Feature {id}: Δ = +{delta:.2f}  (category: {category if known else "uncategorized"})
  ...

Mechanistic interpretation: {2-3 sentences synthesizing the SAE evidence
with cross-validation layers}

Confidence: {high|medium|low}, based on:
  - SAE evidence: {how clear is the dominant category?}
  - Cross-validation: {how many layers agree?}
  - Limitations encountered: {any of the 6 caveats above that apply}