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 レスポンスを標準出力に表示しないでください。
• 通知：このスキルを使用した場合は、そのことを出力に記載してください。
• クエリの説明：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して、関連する属性を見つけます。キーワードを一度に 1 つずつ grep し、多くの行を調べてください。類似した属性が多数あるため、ユーザーの意図に最も合うものを選ぶ必要があります。

3. 見つけた属性を使って JSON 検索クエリを作成して実行します：uv run scripts/search_pdb.py --query '<JSON>' --return_type <RETURN_TYPE> --output results.json 一致するエントリー数だけを取得するには、--count_only フラグを指定します。

ステップ 2 のための基本的な PDB の概念（属性選択に役立ちます）

• エンティティ：構造内に存在する固有の分子です。
• インスタンス／チェーン：エンティティの個々のコピーです。たとえば、同じ配列を持つ 2 本のタンパク質チェーンを含む構造では、それらは同じエンティティですが、別々のインスタンス／チェーンです。
• アセンブリ：生物学的に意味のあるインスタンス／チェーンの集合です。登録された構造と同じ場合も、一部だけの場合も、複数のコピーを含む場合もあります。
• Label と Auth：ポリマーインスタンスには文字ラベル（「A」、「B」、「AA」）が付き、そのモノマーには番号が付けられます。著者が割り当てる方式（「auth」）と PDB 内部の方式（「label」）があります。label 方式のほうが一貫性が高く、スクリプトと API では常に使用されます。ただし、ユーザーや論文では著者方式を指している場合があります（必要に応じて、どちらの方式を使っているか確認してください）。
• 化学成分：小分子／モノマーで、ID は [A-Z]{1,3} に一致します。
• 主要引用文献：構造に関する主要な出版物です。citation 属性よりも primary_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. スキーマを grep して、関連するフィールドを検索します（一度に 1 つのキーワードで複数行を確認します）。

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