pdb-database

RCSB Protein Data Bank 技能

前提条件

1. uv：阅读 uv 技能，并按照其中的设置说明确保 已安装 uv 且其位于 PATH 中。

2. 用户通知：如果工作区根目录中尚不存在 .licenses/pdb_database_LICENSE.txt，则 (1) 显著提醒用户查看 https://www.rcsb.org/pages/usage-policy 上的条款，然后 (2) 创建该文件，记录通知文本和时间戳。

核心规则

• 始终优先使用提供的脚本。只有在万不得已时才使用 curl、urllib、原始 HTTP 请求或其他方法访问 PDB API。 脚本会自动执行所需的速率限制。
• 始终将输出重定向到文件。使用例如 jq、grep 或简短的 Python 代码片段解析输出。请勿将大型 API 响应打印到 stdout， 以免输出被截断。
• 通知：如果使用了此技能，请确保在输出中提及。
• 说明查询内容：完成使用 PDB JSON/GraphQL 查询的任务后，用清晰的语言说明查询的作用，以便用户纠正任何错误假设。

基于属性的搜索工作流

1. 获取相关架构，以发现可搜索的属性名称。对于结构属性：uv run scripts/fetch_schema.py --api search_structure --output schema_structure.txt 对于化学属性：uv run scripts/fetch_schema.py --api search_chemical --output schema_chemical.txt

2. 使用 Grep 搜索架构，查找相关属性。每次搜索一个关键词，并检查多行内容——有许多相似属性，必须选择最符合用户意图的属性。

3. 编写并运行 JSON 搜索查询，使用发现的属性：uv run scripts/search_pdb.py --query '<JSON>' --return_type <RETURN_TYPE> --output results.json 添加 --count_only 标志，只获取匹配条目的数量。

步骤 2：一些基础 PDB 概念（有助于选择属性）

• 实体：结构中发现的唯一分子。
• 实例 / 链：实体的某个特定副本。例如，如果一个结构包含两条序列相同的蛋白质链，它们属于同一个实体，但属于不同的实例 / 链。
• 装配体：具有生物学意义的一组实例 / 链。它可能与提交的结构相同，也可能是其子集，或包含多个副本。
• Label 与 Auth：聚合物实例会被赋予字母标签（“A”“B”“AA”），其单体会被编号。存在由作者指定（“auth”）和 PDB 内部使用（“label”）的两种方案。Label 方案更一致，且脚本和 API 始终使用该方案。不过，用户和论文可能会使用作者方案（必要时请明确说明使用的是哪种方案）。
• 化学组分：一种小分子 / 单体，其 ID 符合 [A-Z]{1,3}
• 主要引文：关于某个结构的主要出版物。优先使用 primary_citation 属性，而非 citation 属性。
• 分辨率：常用的结构质量度量指标（数值越低越好）。通常优先使用 rcsb_entry_info.resolution_combined，它会综合考虑不同的实验方法。

步骤 3：查询示例

# Non-human proteins published in Nature, newest first
uv run scripts/search_pdb.py --query '{ "type": "group", "logical_operator": "and", "nodes": [ { "type": "terminal", "service": "text", "parameters": { "operator": "exact_match", "negation": true, "value": "Homo sapiens", "attribute": "rcsb_entity_source_organism.taxonomy_lineage.name" } }, { "type": "terminal", "service": "text", "parameters": { "operator": "exact_match", "value": "Nature", "attribute": "rcsb_primary_citation.rcsb_journal_abbrev" } } ] }' --return_type entry --sort_by rcsb_accession_info.initial_release_date --sort_direction desc --page_start 0 --rows 100 --output results.json

# Structures containing the chemical component CA (Ca2+ ion)
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "text_chem", "parameters": { "operator": "exact_match", "value": "CA", "attribute": "rcsb_chem_comp_container_identifiers.comp_id" } }' --return_type entry --output results.json

# Number of entries with disulfide bonds
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "text", "parameters": { "operator": "exact_match", "value": "disulfide bridge", "attribute": "rcsb_polymer_struct_conn.connect_type" } }' --return_type entry --count-only --output count.json

常用运算符：exact_match、equals、exists、contains_phrase、 contains_words、in、greater、less

基于相似性的搜索工作流

相似性搜索不需要获取架构。基础示例：

# Sequence similarity
uv run scripts/search_pdb.py --query '{ "query": { "type": "terminal", "service": "sequence", "parameters": { "evalue_cutoff": 1, "identity_cutoff": 0.9, "sequence_type": "protein", "value": "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQ" } }, "request_options": { "scoring_strategy": "sequence" } }' --return_type polymer_entity --output results.json

# Structure similarity
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "structure", "parameters": { "value": {"entry_id": "6LU7", "asym_id": "A"}, "number_of_candidates": 2000 } }' --return_type polymer_entity --output results.json

# Sequence motif match
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "seqmotif", "parameters": { "value": "C-x(2,4)-C-x(3)-[LIVMFYWC]-x(8)-H-x(3,5)-H.", "pattern_type": "prosite", "sequence_type": "protein" } }' --return_type polymer_entity --output results.json

# Chemical descriptor match
uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "chemical", "parameters": { "value": "InChI=1S/C8H9NO2/c1-6(10)9-7-2-4-8(11)5-3-7/h2-5,11H,1H3,(H,9,10)", "type": "descriptor", "descriptor_type": "InChI", "match_type": "graph-strict" } }' --return_type mol_definition --output results.json

更多详情请参见 https://search.rcsb.org/#search-services。

全文搜索工作流

搜索与某个条目相关的所有文本。示例：

uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "full_text", "parameters": { "value": "isopeptide + ( collagen | fibrinogen )" } }' --return_type entry --output results.json

重要：当没有更精确的属性搜索可用时，才将 full_text 搜索作为最后手段。请考虑使用 struct.title 或 rcsb_pubmed_abstract_text 属性。

文件下载工作流

要下载完整的 PDB 条目，请使用 download_coordinate_files.py 脚本。当你需要访问原子坐标、有人请求 pdb / mmcif 文件，或笼统地要求获取 PDB 代码时，请使用此脚本。例如：

uv run scripts/download_coordinate_files.py --ids "4HHB,6BEA" --format "mmcif" --output_dir <OUTPUT_DIR>

元数据查询工作流

如果只需要获取每个条目 / 实体的少量元数据，此流程比下载完整的坐标文件高效得多。

1. 获取相关对象类型的架构。例如：uv run scripts/fetch_schema.py --api data_entry --output schema_entry.txt

2. 在架构中搜索相关字段（一次一个关键词，匹配多行）。

3. 编写并运行 GraphQL 元数据查询：uv run scripts/fetch_pdb_metadata.py --query '<GraphQL>' --output results.json

第 3 步：查询示例

# Fetch structure titles and experimental methods
uv run scripts/fetch_pdb_metadata.py --query '{ entries(entry_ids: ["1STP", "2JEF", "1CDG"]) { rcsb_id struct { title } exptl { method } } }' --output results.json

# Fetch polymer entity taxonomy and cluster membership
uv run scripts/fetch_pdb_metadata.py --query '{ polymer_entities(entity_ids:["2CPK_1","3WHM_1","2D5Z_1"]) { rcsb_id rcsb_entity_source_organism { ncbi_taxonomy_id ncbi_scientific_name } rcsb_cluster_membership { cluster_id identity } } }' --output results.json

# Fetch polymer entity external sequence database accessions
uv run scripts/fetch_pdb_metadata.py --query '{ entries(entry_ids:["7NHM", "5L2G"]){ polymer_entities { rcsb_id rcsb_polymer_entity_container_identifiers { reference_sequence_identifiers { database_accession database_name } } } } }' --output results.json