tooluniverse-protein-structure-retrieval

蛋白质结构数据检索

检索蛋白质结构，并进行消歧、质量评估和全面的元数据整理。

重要：在工具调用中始终使用英文术语。使用用户的语言回复。

查证，不要猜测：切勿假定 PDB ID、分辨率或数据是否可用。始终查询 RCSB/PDBe 和 AlphaFold 进行确认。

领域知识

并非所有结构都同样可靠。分辨率 <2 A 的 X 射线结构适合药物设计。3-4 A 的冷冻电镜结构适合判断折叠，但不适合确定侧链。AlphaFold 对折叠良好的结构域预测效果出色，但对无序区域的预测不可靠。得出结论前，务必检查 pLDDT（AlphaFold）或分辨率（实验结构）。

工作流

Phase 0: Clarify (if needed) → Phase 1: Disambiguate Protein → Phase 2: Retrieve Structures → Phase 3: Report

---

阶段 0：澄清（必要时）

仅在以下情况提问：蛋白质名称有歧义（例如“激酶”）、未指定物种，或不清楚需要实验结构还是 AlphaFold 结构。 以下情况跳过：提供了具体 PDB ID、UniProt 登录号，或蛋白质和物种信息明确无歧义。

---

阶段 1：蛋白质消歧

# By PDB ID: direct retrieval
# By UniProt: get AlphaFold + search experimental structures
af_structure = tu.tools.alphafold_get_prediction(uniprot_id=uniprot_id)
# By protein name: search
result = tu.tools.PDBeSearch_search_structures(query=protein_name)

身份核对清单

• 确认蛋白质名称/基因，并确认物种
• UniProt 登录号（如有），并注明同工型/变体（如相关）

---

阶段 2：数据检索（内部）

静默检索。不要叙述检索过程。

pdb_id = "4INS"

# Search, metadata, quality, ligands, similar structures
result = tu.tools.PDBeSearch_search_structures(query=name)
metadata = tu.tools.get_protein_metadata_by_pdb_id(pdb_id=pdb_id)
exp = tu.tools.RCSBData_get_entry(pdb_id=pdb_id)
quality = tu.tools.PDBeValidation_get_quality_scores(pdb_id=pdb_id)
ligands = tu.tools.PDBe_get_structure_ligands(pdb_id=pdb_id)  # data.ligands[]
similar = tu.tools.PDB_search_similar_structures(query=pdb_id, search_type="structure")  # data.results[] with rank, score
# By UniProt accession: all PDB entries, and ligand-binding residues across entries
entries = tu.tools.PDBeSIFTS_get_all_structures(uniprot_accession=uniprot_id)  # data.pdb_entries[]
sites = tu.tools.PDBe_KB_get_ligand_sites(uniprot_accession=uniprot_id)  # data.ligands[]

# PDBe additional data
summary = tu.tools.pdbe_get_entry_summary(pdb_id=pdb_id)
molecules = tu.tools.pdbe_get_entry_molecules(pdb_id=pdb_id)

# AlphaFold (when no experimental structure, or for comparison)
af = tu.tools.alphafold_get_prediction(uniprot_id=uniprot_id)

后备方案

首选	后备方案
RCSB 搜索	PDBe 搜索
get_protein_metadata	pdbe_get_entry_summary
实验结构	AlphaFold 预测
get_protein_ligands	PDBe_get_structure_ligands（按 PDB ID）或 PDBe_KB_get_ligand_sites（按 UniProt 登录号）
没有可用的 AlphaFold 模型（多结构域蛋白，特定范围的 pLDDT 较低）	使用 SwissModel_get_models 筛选对应残基 range 的模型——该数据库包含按结构域划分的同源模型，AlphaFold 的单个全长模型可能无法很好地解析这些结构域

SWISS-MODEL Repository（同源模型 + 重新索引的实验结构）

使用 SwissModel_get_summary(uniprot_id=...)，一次调用即可检查“是否存在同源模型，以及模型质量如何”——它会返回 SWISS-MODEL 中该登录号覆盖度最高的条目。重要提示：它返回的“最佳”条目可能是按 UniProt 残基范围重新索引的实验性 PDB 结构（经实时验证：对于 EGFR/P00533，get_summary 的 best_model 是一个 X-RAY DIFFRACTION 条目，而不是同源模型）——请检查 best_model.method，不要想当然地认为“最佳模型”就是“计算得到的同源模型”。

若要专门获取真正计算得到的同源模型，请调用 SwissModel_get_models(uniprot_id=..., provider="swissmodel")——provider="pdb" 则只返回重新索引的实验结构；省略 provider 会同时返回两者。其他筛选条件包括：range（残基范围；对于某一区域 AlphaFold 置信度较低的大型多结构域蛋白很有用）和 template（指定的 PDB 模板 ID）。

SwissModel_download_pdb(uniprot_id=..., provider=...) 会获取实际的 ATOM/HETATM 坐标文本（而不只是 URL），供后续对接/可视化使用——筛选条件与 get_models 相同。SwissModel_get_models_batch(uniprot_ids=[...]) 一次调用最多可查询 250 个登录号；在决定哪些蛋白需要改用 AlphaFold/ESMFold 前，可用它批量检查基因列表中的模型可用性。

质量指标注意事项（经实时验证）：在测试的所有真实同源模型条目中（EGFR 的 2 个 SWISS-MODEL 模型），qmean_global/qmean_z_score 均为 null——QMEAN 经常缺失，不能始终依赖这一指标。请使用 coverage（模型涵盖 UniProt 序列的比例）、template（用于构建模型的 PDB 结构）和 method 作为更稳定的质量信号；有 QMEAN 时可将其作为额外参考，但不要把它当作必需的检查项。

何时选择 SWISS-MODEL 而非 AlphaFold：对于任何经过 UniProt 审核的蛋白，AlphaFold（见上文）都是默认的单模型参考。以下情况可优先考虑 SWISS-MODEL：（a）需要多个基于不同模板构建的备选模型进行比较；（b）大型蛋白的某个区域 AlphaFold 置信度较低，可尝试使用模板覆盖度更好的结构域特异性同源模型；（c）需要一次检查多个登录号，并希望批量查询，而非分别调用 AlphaFold N 次。

3D-Beacons（跨所有结构提供方的元聚合器）

当你还不清楚哪个结构来源对某个 UniProt 登录号的覆盖最全面或质量最好时，ThreeDBeacons_get_structure_summary(accession=...) 是最佳的首次调用——它会同时查询 PDBe、SWISS-MODEL、AlphaFold DB、AlphaFill 和 ModelArchive，并返回 by_provider 计数以及 by_category 分类汇总（EXPERIMENTALLY DETERMINED / TEMPLATE-BASED / AB-INITIO）。真实示例（已实时验证）：EGFR/P00533 → total_structures: 426，by_provider: {"PDBe": 412, "SWISS-MODEL": 2, "AlphaFold DB": 6, "AlphaFill": 1, "ModelArchive": 5}——这证实该蛋白的结构绝大多数已由实验结构覆盖，而且上文阶段中的 2 个 SWISS-MODEL 条目只是实际可用结构的一小部分；如果 3D-Beacons 显示 PDBe 的数量丰富得多，就不要只看 SWISS-MODEL 自己的列表。

ThreeDBeacons_get_structures(accession=..., category=..., provider=..., max_results=...) 返回单个结构/模型记录（而不只是计数）——可按 category 或 provider 筛选，在其他位置获取详情前缩小范围。ThreeDBeacons_get_annotations(accession=..., type=..., provider=...) 将残基级注释（例如 type="DOMAIN"、type="BINDING"）映射到蛋白质的 3D 模型上——真实示例：对 BRCA1/P38398 使用 type="DOMAIN" 会返回实际的结构域到残基映射；而对 P04637 查询 type="BINDING" 可能会合理地返回零条注释（annotation_count: 0）——此处结果为空，意味着聚合来源中不存在此类注释，并非调用失败。

工作流：对任何 UniProt 登录号，都先使用 ThreeDBeacons_get_structure_summary 进行初步了解，然后再决定是否具体深入查询 PDBe/RCSB（阶段 2）、AlphaFold 或 SWISS-MODEL。

PDB-REDO（重新精修的实验结构）

PDB-REDO 会使用当前的软件和参数自动重新精修每个 X 射线 PDB 条目，通常能提升原始提交结构的精修质量。PDB_REDO_get_structure_quality(pdb_id=...) 会返回重新精修结构的详细精修指标（晶胞轴、B 因子、实空间/工作集相关系数 CCFFIN/CCWFIN、分辨率 DATARESH、完整度）——真实示例（已实时验证）：PDB 4hjo（一个 EGFR 结构）→ DATARESH: 2.75、CCWFIN: 0.93、COMPLETED: 96.9。PDB_REDO_get_version_info(pdb_id=...) 会返回同一条目的重新精修来源/版本元数据。

使用时机：当下游药物设计决策对精度要求较高时，优先使用 PDB-REDO 的重新精修指标，而非原始 PDB 提交中注明的分辨率/R 因子——重新精修可能显著改变 R-free，甚至修正原始提交中模型的小错误。

---

阶段 3：报告结构概况

以结构概况报告的形式呈现。隐藏搜索过程。包括：

1. 搜索摘要：查询内容、物种、实验结构 + AlphaFold 结构数量
2. 最佳结构：PDB ID、UniProt、物种、方法、分辨率、日期、质量评估
3. 实验详情：方法、分辨率、R 因子、R-free、空间群
4. 组成：链、残基（覆盖率%）、配体、水、金属
5. 结合配体：配体 ID、名称、类型、结合位点
6. 结合位点详情（用于药物发现）：位置、关键残基、成药性
7. 备选结构：按质量排序，并标注分辨率、方法、配体
8. AlphaFold 预测：UniProt、模型版本、pLDDT 置信度分布、使用场景
9. 结构比较：各结构的分辨率、完整度、配体
10. 下载链接：PDB/mmCIF/AlphaFold 格式、数据库 URL

---

质量评估

实验结构

等级	标准
优秀	X-ray <1.5A，完整，R-free <0.22
高	X-ray <2.0A 或 Cryo-EM <3.0A
良好	X-ray 2.0-3.0A 或 Cryo-EM 3.0-4.0A
中等	X-ray >3.0A 或 NMR ensemble
低	>4.0A、不完整或存在问题

分辨率的适用场景

<1.5A：原子级细节、氢键分析。1.5-2.0A：药物设计。2.0-2.5A：基于结构的设计。2.5-3.5A：整体架构。>3.5A：仅用于结构域排列。

AlphaFold 置信度（pLDDT）

90：置信度极高，接近实验结果。70-90：主链结构良好。50-70：不确定/灵活。<50：可能无序。

---

错误处理

错误	响应
"PDB ID not found"	确认格式为 4 个字符，并检查是否已废弃
"No structures"	提供 AlphaFold 选项，并建议相似蛋白质
"Download failed"	重试一次，并提供备用链接
"Resolution unavailable"	可能是 NMR/模型结构，在评估中注明

---

工具参考

RCSB PDB：PDBeSearch_search_structures（搜索）、get_protein_metadata_by_pdb_id（基本信息）、RCSBData_get_entry（详情）、PDBeValidation_get_quality_scores（质量）、PDBe_get_structure_ligands（条目中的配体）、PDBe_KB_get_ligand_sites（UniProt 登录号对应的配体结合残基）、PDBeSIFTS_get_all_structures（UniProt 登录号对应的所有 PDB 条目）、PDB_search_similar_structures（相似结构）

PDBe：pdbe_get_entry_summary（概览）、pdbe_get_entry_molecules（实体）、pdbe_get_entry_experiment（实验信息）、PDBe_KB_get_ligand_sites（口袋）

AlphaFold：alphafold_get_prediction（获取预测结果）、alphafold_get_summary（搜索）

SWISS-MODEL：SwissModel_get_summary（最佳可用模型，单次调用）、SwissModel_get_models（列出所有模型，可按 range/provider/template 筛选）、SwissModel_download_pdb（实际坐标文本）、SwissModel_get_models_batch（单次调用最多处理 250 个 UniProt 登录号）

3D-Beacons：ThreeDBeacons_get_structure_summary（跨提供方计数，最适合作为首次调用）、ThreeDBeacons_get_structures（单个结构/模型记录，可按 category/provider 筛选）、ThreeDBeacons_get_annotations（映射到 3D 模型上的残基级结构域/结合位点注释）

PDB-REDO：PDB_REDO_get_structure_quality（重新精修的 X-ray 指标）、PDB_REDO_get_version_info（重新精修来源）