alterlab-pdb

PDB 数据库

概述

RCSB PDB 是全球生物大分子 3D 结构数据存储库。您可以搜索结构、获取坐标和元数据，并在约 260,000 个实验测定的条目（截至 2026-09）以及从 AlphaFold DB 和 ModelArchive 导入的计算结构模型（CSM）中进行序列和结构相似性搜索。

脚本

scripts/query_pdb.py — RCSB Search、Data 和文件 API（仅使用标准库，JSON 输出到 stdout）：

python scripts/query_pdb.py search hemoglobin --rows 25     # full-text search (entry IDs)
python scripts/query_pdb.py entry 4HHB                      # entry metadata
python scripts/query_pdb.py download 4HHB --format cif      # download coordinates

何时使用此技能

在以下情况下应使用此技能：

• 按文本、序列或结构相似性搜索蛋白质或核酸的 3D 结构
• 下载 PDB、mmCIF 或 BinaryCIF 格式的坐标文件
• 获取结构元数据、实验方法或质量指标
• 对多个结构执行批量操作
• 将 PDB 数据集成到药物发现、蛋白质工程或结构生物学研究的计算工作流中

不适用的情况

场景	改用
缺少实验数据的蛋白质 AI 预测结构	alterlab-alphafold-db
蛋白质序列、功能注释或登录号映射	alterlab-uniprot
蛋白质的结构域／家族分类	alterlab-interpro
预测新的复合物或共折叠结构	alterlab-boltz
将配体对接到结构中	alterlab-diffdock

核心功能

1. 搜索结构

使用各种搜索条件查找 PDB 条目：

文本搜索： 按蛋白质名称、关键词或描述搜索

from rcsbapi.search import TextQuery
query = TextQuery("hemoglobin")
results = list(query())
print(f"Found {len(results)} structures")

属性搜索： 查询特定属性（生物体、分辨率、方法等）

from rcsbapi.search import AttributeQuery
from rcsbapi.search import search_attributes as attrs

# Find human protein structures (idiomatic form — recommended)
query = attrs.rcsb_entity_source_organism.scientific_name == "Homo sapiens"
results = list(query())

# OR explicit AttributeQuery with a dotted-path STRING (not the Attr object):
query = AttributeQuery(
    attribute="rcsb_entity_source_organism.scientific_name",
    operator="exact_match",
    value="Homo sapiens",
)
results = list(query())

序列相似性： 查找与给定序列相似的结构

from rcsbapi.search import SeqSimilarityQuery

query = SeqSimilarityQuery(
    value="MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVIDGETCLLDILDTAGQEEYSAMRDQYMRTGEGFLCVFAINNTKSFEDIHHYREQIKRVKDSEDVPMVLVGNKCDLPSRTVDTKQAQDLARSYGIPFIETSAKTRQGVDDAFYTLVREIRKHKEKMSKDGKKKKKKSKTKCVIM",
    evalue_cutoff=0.1,
    identity_cutoff=0.9,
    sequence_type="protein"
)
results = list(query())

结构相似性： 查找 3D 几何结构相似的结构

from rcsbapi.search import StructSimilarityQuery

# structure_search_type is "entry_id" (default), "file_url", or "file_upload";
# pass assembly_id or chain_id to pick what is compared ("entry"/"chain"/"assembly"
# are not valid search types and return HTTP 400)
query = StructSimilarityQuery(
    entry_id="4HHB",   # Hemoglobin
    assembly_id="1",   # or chain_id="A"
)
results = list(query())

组合查询： 使用逻辑运算符构建复杂搜索

from rcsbapi.search import search_attributes as attrs

# High-resolution human proteins
query1 = attrs.rcsb_entity_source_organism.scientific_name == "Homo sapiens"
query2 = attrs.rcsb_entry_info.resolution_combined < 2.0
combined_query = query1 & query2  # AND operation
results = list(combined_query())

2. 获取结构数据

访问特定 PDB 条目的详细信息：

基本条目信息：

from rcsbapi.data import DataQuery

# Get entry-level data
query = DataQuery(
    input_type="entries",
    input_ids=["4HHB"],
    return_data_list=["struct.title", "exptl.method"],
)
data = query.exec()  # synchronous; returns a dict
entry = data["data"]["entries"][0]
print(entry["struct"]["title"])
print(entry["exptl"][0]["method"])

聚合物实体信息：

from rcsbapi.data import DataQuery

# Get protein/nucleic acid information
query = DataQuery(
    input_type="polymer_entities",
    input_ids=["4HHB_1"],
    return_data_list=["entity_poly.pdbx_seq_one_letter_code"],
)
data = query.exec()
entity = data["data"]["polymer_entities"][0]
print(entity["entity_poly"]["pdbx_seq_one_letter_code"])

构建查询（底层使用 GraphQL）：

from rcsbapi.data import DataQuery

# DataQuery builds the GraphQL query for you from input_type/input_ids/return_data_list;
# there is no separate fetch(query_type="graphql", ...) entry point.
query = DataQuery(
    input_type="entries",
    input_ids=["4HHB"],
    return_data_list=[
        "struct.title",
        "exptl.method",
        "rcsb_entry_info.resolution_combined",
        "rcsb_entry_info.deposited_atom_count",
    ],
)
# Inspect the auto-generated GraphQL / open it in the editor:
print(query.get_editor_link())
data = query.exec()

3. 下载结构文件

获取各种格式的坐标文件：

下载方式：

• PDB 格式（旧版文本格式）：https://files.rcsb.org/download/{PDB_ID}.pdb
• mmCIF 格式（现代标准）：https://files.rcsb.org/download/{PDB_ID}.cif
• BinaryCIF（压缩二进制格式）：使用 ModelServer API 高效访问
• 生物学组装体：https://files.rcsb.org/download/{PDB_ID}.pdb1（用于组装体 1）

下载示例：

import requests

pdb_id = "4HHB"

# Download PDB format
pdb_url = f"https://files.rcsb.org/download/{pdb_id}.pdb"
response = requests.get(pdb_url)
with open(f"{pdb_id}.pdb", "w") as f:
    f.write(response.text)

# Download mmCIF format
cif_url = f"https://files.rcsb.org/download/{pdb_id}.cif"
response = requests.get(cif_url)
with open(f"{pdb_id}.cif", "w") as f:
    f.write(response.text)

4. 使用结构数据

对获取的结构进行常见操作：

解析和分析坐标： 使用 BioPython 或其他结构生物学库处理下载的文件：

from Bio.PDB import PDBParser

parser = PDBParser()
structure = parser.get_structure("protein", "4HHB.pdb")

# Iterate through atoms
for model in structure:
    for chain in model:
        for residue in chain:
            for atom in residue:
                print(atom.get_coord())

提取元数据：

from rcsbapi.data import DataQuery

# Get experimental details
query = DataQuery(
    input_type="entries",
    input_ids=["4HHB"],
    return_data_list=[
        "rcsb_entry_info.resolution_combined",
        "exptl.method",
        "rcsb_accession_info.deposit_date",
    ],
)
data = query.exec()["data"]["entries"][0]

resolution = data.get("rcsb_entry_info", {}).get("resolution_combined")
method = data.get("exptl", [{}])[0].get("method")
deposition_date = data.get("rcsb_accession_info", {}).get("deposit_date")

print(f"Resolution: {resolution[0] if resolution else None} Å")  # resolution_combined is a list
print(f"Method: {method}")
print(f"Deposited: {deposition_date}")

5. 批量操作

高效处理多个结构：

from rcsbapi.data import DataQuery

pdb_ids = ["4HHB", "1MBN", "1GZX"]  # Hemoglobin, myoglobin, etc.

# A single DataQuery can fetch all entries at once. Use fully qualified paths:
# source organism lives on polymer entities, not on the entry.
query = DataQuery(
    input_type="entries",
    input_ids=pdb_ids,
    return_data_list=[
        "rcsb_id",
        "struct.title",
        "rcsb_entry_info.resolution_combined",
        "polymer_entities.rcsb_entity_source_organism.scientific_name",
    ],
)

results = {}
for data in query.exec()["data"]["entries"]:
    pdb_id = data["rcsb_id"]
    resolution = (data.get("rcsb_entry_info") or {}).get("resolution_combined") or [None]
    entities = data.get("polymer_entities") or [{}]
    organisms = (entities[0].get("rcsb_entity_source_organism") or [{}])
    results[pdb_id] = {
        "title": data["struct"]["title"],
        "resolution": resolution[0],
        "organism": organisms[0].get("scientific_name"),
    }

# Display results
for pdb_id, info in results.items():
    print(f"\n{pdb_id}: {info['title']}")
    print(f"  Resolution: {info['resolution']} Å")
    print(f"  Organism: {info['organism']}")

安装 Python 软件包

安装官方 RCSB PDB Python API 客户端（rcsb-api，当前主版本为 1.x；此处示例适用于 >=1.7）：

uv pip install "rcsb-api>=1.7"

rcsb-api 软件包通过 rcsbapi.search 和 rcsbapi.data 模块统一访问 Search 和 Data API。（旧版 rcsbsearchapi 软件包已由 rcsb-api 取代，且其 import rcsbsearchapi 路径已移除——新代码请优先使用 rcsb-api。）

scripts/query_pdb.py 辅助脚本无需安装这些内容——它仅使用 Python 标准库调用公共 REST API。

常见用例

药物发现

• 搜索药物靶点的结构
• 分析配体结合位点
• 比较蛋白质－配体复合物
• 识别相似的结合口袋

蛋白质工程

• 查找同源结构以用于建模
• 分析序列－结构关系
• 比较突变体结构
• 研究蛋白质稳定性和动力学

结构生物学研究

• 下载结构以进行计算分析
• 构建基于结构的比对
• 分析结构特征（次级结构、结构域）
• 比较实验方法和质量指标

教育与可视化

• 检索结构用于教学
• 生成分子可视化图
• 探索结构与功能之间的关系
• 研究进化保守性

核心概念

PDB ID： 每个结构条目的唯一 4 字符标识符（例如，“4HHB”）。AlphaFold 和 ModelArchive 条目以“AF_”或“MA_”为前缀。

mmCIF/PDBx： 一种现代文件格式，采用键值结构，取代了用于大型结构的旧版 PDB 格式。

生物学组装体： 大分子的功能形式，可能包含来自不对称单元的多条链的多个拷贝。

分辨率： 衡量晶体结构细节程度的指标（数值越低，细节越丰富）。高质量结构的典型范围为 1.5-3.5 Å。

实体： 结构中的独特分子组分（蛋白质链、DNA、配体等）。

资源

此技能在 references/ 目录中包含参考文档：

references/api_reference.md

全面的 API 文档，涵盖：

• 详细的 API 端点规范
• 高级查询模式和示例
• 数据架构参考
• 速率限制和最佳实践
• 常见问题排查

当你需要深入了解 API 功能、构建复杂查询或详细了解数据架构时，请使用此参考文档。

其他资源

• RCSB PDB 网站： https://www.rcsb.org
• PDB-101 教育门户： https://pdb101.rcsb.org
• API 文档： https://www.rcsb.org/docs/programmatic-access/web-apis-overview
• Python 软件包文档： https://rcsbapi.readthedocs.io/
• Data API 文档： https://data.rcsb.org/
• GitHub 仓库： https://github.com/rcsb/py-rcsb-api