tooluniverse-protein-structural-annotation-pdb

根据 PDB 进行蛋白质结构注释

对于目标蛋白质链的每个残基，判断它是否位于结合界面或配体口袋中、是埋藏还是溶剂暴露，以及（可选）它属于哪个二级结构元件。这类注释为任何 DMS 热图或逐残基解读提供锚点，使其对应到蛋白质实际的物理环境。

---

何时使用此技能

• 为 DMS 热图构建逐残基注释轨道
• 判断感兴趣的变体位于界面、口袋还是核心——这一背景常常有助于区分合理的作用机制
• 根据蛋白质已知的生物学特性，解读某个位置的 SAE 特征下降（配体口袋残基处的特征下降与表面残基处的下降含义不同）

不适用于：

• 多构象集合或 NMR 结构比较 → 使用 tooluniverse-computational-biophysics
• 未知配体时检测整个结构中的口袋 → 使用对接工具（例如 SwissDock）或 PDBe 预计算口袋

---

必需输入

输入	格式	示例
PDB ID	4 个字符	6VJJ（KRAS-RAF1-GTP 类似物）
目标链	单个字符	A
伙伴链	链 ID 列表	["B"]
配体 resname	3 字母 PDB 名称	["GNP", "MG"]

可选项：

• distance_cutoff（默认值为 5.0 Å）
• core_rsa_cutoff（默认值为 0.25）
• include_secondary_structure（默认值为 false；若为 true，则使用 PDBe REST）
• 对于本地或预测结构，使用 pdb_content 代替 pdb_id

---

工作流

步骤 1（可选）：查找相关 PDB

如果你只有 UniProt 登录号或基因符号，请先选择一个结构：

# PDBe's curated UniProt→PDB mapping (recommended; ranks by coverage + resolution)
PDBeSIFTS_get_best_structures(uniprot_accession="P01116")
# Returns a ranked list of PDB IDs for KRAS with chain mapping

# Or full list (unranked)
PDBeSIFTS_get_all_structures(uniprot_accession="P01116")

# RCSB advanced search (free-text, when you don't have a UniProt yet)
RCSBAdvSearch_search_structures(query="KRAS GTP complex")

选择包含正确复合物的结构：其中应包含你关注的结合伙伴链、相关配体，且分辨率足以进行基于距离的分类（≤ 3 Å 是稳妥的默认值）。

步骤 2：运行注释

Structure_annotate_per_residue(
    pdb_id="6VJJ",
    target_chain="A",
    partner_chains=["B"],
    ligand_resnames=["GNP", "MG"],
    distance_cutoff=5.0,
    core_rsa_cutoff=0.25,
    include_secondary_structure=False,
)

对目标链的每个残基返回 annotations: List[{position, aa, dist_partner, dist_ligand, rsa, region, is_core, ss_element?}]。对于 6VJJ 中的 KRAS，这会生成 168 行。

步骤 3：合并前验证编号

PDB 残基编号可能存在不易察觉的偏移——晶体结构构建体会添加 N 端克隆残基，已发表的图示有时也会使轨道相对于面板序列发生偏移。务必用一个定位点进行验证：

# Get the canonical reference sequence
UniProt_get_sequence_by_accession(accession="P01116")
# Then spot-check: KRAS canonical position 12 should be glycine
assert annotations[11]["aa"] == "G"  # 1-indexed position 12, 0-indexed index 11

如果定位点不匹配，请明确记录偏移量（例如 pdb_pos = uniprot_pos + offset），然后再进行任何下游合并。不要在不注明的情况下重设位置编号。

步骤 4：结合二级结构（可选）

如果设置 include_secondary_structure=True，该工具会从 PDBe REST 获取逐残基的螺旋、链或卷曲信息。或者，也可以单独使用专用的 PDBe 二级结构工具：

pdbe_get_entry_secondary_structure(pdb_id="6VJJ")
# Returns per-chain helix + strand ranges

步骤 5：使用注释

返回的表以从 1 开始的标准残基编号为键。典型的下游用途：

用途	要读取的字段
变体 X 是否位于口袋中？	by_pos = {a["position"]: a for a in annotations}; by_pos[X]["region"] in ("ligand", "both") — 按 position 字段索引，而不是按列表索引（PDB 残基编号可能不从 1 开始，也可能不连续）
构建 DMS 热图注释轨道	[(r["position"], r["region"], r["is_core"], r.get("ss_element"))]
筛选配体结合残基处的 SAE 热点特征	按 region == "ligand" 筛选聚类
比较埋藏与表面信号	按 is_core 分组统计

---

结果解读表

区域标签	生物学含义	常见功能角色
interface	距离伙伴链不超过 distance_cutoff	蛋白质-蛋白质结合残基；变体通常会破坏复合物形成
ligand	距离配体的重原子不超过 distance_cutoff	口袋残基；变体通常会破坏底物 / 辅因子 / 药物结合
both	两者皆是	变构或共享表面残基
other	两者皆非	表面残基（若不是 is_core）或核心残基（若是 is_core）——变体会通过稳定性或远端效应产生影响
is_core=true	RSA < core_rsa_cutoff（默认值为 0.25）	埋藏残基；变体通常会使蛋白质折叠不稳定

---

必须如实说明的局限

1. 仅使用一种构象。静态晶体结构无法呈现其他构象或诱导契合结合。某个残基在一种构象中可能位于口袋处，在另一种构象中却可能远离口袋。请根据你的问题选择结合状态相符的结构。
2. 编号容易出错。晶体结构构建体可能添加 N 端标签，或省略无序的 N/C 端。将其与序列或其他注释来源关联前，务必使用标志位点核实。此工具无法替你检测不易察觉的偏移。
3. 距离阈值是惯例，并非绝对标准。文献中默认使用 5.0 Å。若要更严格地判定口袋，可收紧至 4.0 Å；若要纳入第二壳层残基，可放宽至 6.0 Å。
4. 对于较小或不寻常的结构，freesasa 的 RSA 可能超过 1.0，因为最大 ASA 参考值是根据典型蛋白质环境校准的。对于真实且折叠良好的蛋白质，数值通常集中在 [0, 1.2]；可将其视为分数来解读，但应把极端值视为需要检查的信号。
5. 允许 partner_chains=[]，但此时所有 dist_partner 值均为 null——将完全跳过界面分析。
6. 仅检测 HETATM 配体。链中已有的修饰残基（例如磷酸化残基）不会被识别为配体——它们属于链的一部分。

---

交叉引用

工具	作用	用途
Structure_annotate_per_residue	此技能的原子级工具	执行注释
PDBeSIFTS_get_best_structures	UniProt → 排序后的 PDB 列表	第 1 步
PDBeSIFTS_get_all_structures	UniProt → 完整 PDB 列表	第 1 步
RCSBAdvSearch_search_structures	RCSB 自由文本搜索	第 1 步
UniProt_get_sequence_by_accession	标准序列	第 3 步（核实编号）
pdbe_get_entry_secondary_structure	仅获取 SS	第 4 步的替代方案
tooluniverse-residue-functional-mechanism-interpretation	下游使用方	解读 DMS 热点时，将此注释用作结构证据层；该技能还会在第 7 步绘制带注释的 DMS 热图