alterlab-pdb

PDB データベース

概要

RCSB PDB は、生体高分子の 3D 構造データを収録する世界的なリポジトリです。構造を検索し、座標とメタデータを取得し、約 260,000 件の実験的に決定されたエントリー（2026-09）に加えて、AlphaFold DB と ModelArchive から取り込まれた計算構造モデル（CSM）を対象に、配列および構造の類似性検索を実行できます。

スクリプト

scripts/query_pdb.py — RCSB Search、Data、ファイル API（標準ライブラリのみ、JSON を標準出力に出力）：

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 API と 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