tooluniverse-protein-structural-annotation-pdb

PDB からのタンパク質構造アノテーション

標的タンパク質鎖の各残基について、結合界面に位置するか、リガンドポケット内にあるか、埋もれているか溶媒に露出しているか、さらに（任意で）どの二次構造要素に属するかを分類します。このアノテーショントラックは、DMS ヒートマップや残基ごとの解釈を、タンパク質の実際の物理的コンテキストに結び付ける基盤となります。

---

このスキルを使う場面

• DMS ヒートマップ用の残基ごとのアノテーショントラックを作成する
• 注目するバリアントが界面、ポケット、コアのどこにあるかを判断する — こうしたコンテキストが、妥当なメカニズムを見分ける手がかりとなることがよくあります
• ある位置での SAE 特徴量の低下を、タンパク質の既知の生物学的性質に照らして解釈する（リガンドポケット残基での特徴量の低下と、表面残基での低下では意味が異なります）

対象外：

• 複数コンフォマーのアンサンブルや NMR 構造の比較 → tooluniverse-computational-biophysics を使用します
• 既知のリガンドがない状態での全構造のポケット検出 → ドッキングツール（例：SwissDock）または PDBe の事前計算済みポケットを使用します

---

必要な入力

入力	形式	例
PDB ID	4 文字	6VJJ（KRAS-RAF1-GTP アナログ）
標的鎖	1 文字	A
パートナー鎖	鎖 ID のリスト	["B"]
リガンドの resname	3 文字の PDB 名	["GNP", "MG"]

任意：

• distance_cutoff（デフォルト 5.0 Å）
• core_rsa_cutoff（デフォルト 0.25）
• include_secondary_structure（デフォルトは false。有効にすると PDBe REST を使用します）
• ローカル構造または予測構造の場合は、pdb_id の代わりに pdb_content

---

ワークフロー

ステップ 1（任意）：該当する PDB を探す

UniProt アクセッションまたは遺伝子シンボルしかない場合は、まず構造を選びます：

# PDBe's curated UniProt→PDB mapping (recommended; ranks by coverage + resolution)
PDBeSIFTS_get_best_structures(uniprot_accession="P01116")
# Returns a ranked list of PDB IDs for KRAS with chain mapping

# Or full list (unranked)
PDBeSIFTS_get_all_structures(uniprot_accession="P01116")

# RCSB advanced search (free-text, when you don't have a UniProt yet)
RCSBAdvSearch_search_structures(query="KRAS GTP complex")

適切な複合体を含む構造を選びます。対象の結合パートナー鎖と関連するリガンドが含まれ、距離に基づく分類に十分な分解能を備えているものを選んでください（≤ 3 Å が安全なデフォルトです）。

ステップ 2：アノテーションを実行する

Structure_annotate_per_residue(
    pdb_id="6VJJ",
    target_chain="A",
    partner_chains=["B"],
    ligand_resnames=["GNP", "MG"],
    distance_cutoff=5.0,
    core_rsa_cutoff=0.25,
    include_secondary_structure=False,
)

標的鎖の各残基について、annotations: List[{position, aa, dist_partner, dist_ligand, rsa, region, is_core, ss_element?}] を返します。6VJJ の KRAS の場合、168 行が得られます。

ステップ 3：結合する前に残基番号を確認する

PDB の残基番号には気付かないオフセットが含まれることがあります。結晶構造用コンストラクトには N 末端のクローニング残基が追加されており、論文の図ではトラックの番号がパネルの配列に対してずれている場合もあります。必ず目印となる残基で確認してください：

# Get the canonical reference sequence
UniProt_get_sequence_by_accession(accession="P01116")
# Then spot-check: KRAS canonical position 12 should be glycine
assert annotations[11]["aa"] == "G"  # 1-indexed position 12, 0-indexed index 11

目印が一致しない場合は、下流で結合する前にオフセットを明示的に記録します（例：pdb_pos = uniprot_pos + offset）。位置番号を黙って付け直さないでください。

ステップ 4：二次構造と組み合わせる（任意）

include_secondary_structure=True を設定すると、ツールは PDBe REST から残基ごとのヘリックス／ストランド／コイル情報を取得します。あるいは、専用の PDBe 二次構造ツールを別途使用できます：

pdbe_get_entry_secondary_structure(pdb_id="6VJJ")
# Returns per-chain helix + strand ranges

ステップ 5：アノテーションを使用する

返されるテーブルは、1 から始まる標準残基番号をキーとしています。一般的な下流での用途：

使用例	参照するフィールド
バリアント X はポケット内にあるか？	by_pos = {a["position"]: a for a in annotations}; by_pos[X]["region"] in ("ligand", "both") — リストのインデックスではなく、position フィールドで参照します（PDB の残基番号は 1 から始まるとは限らず、連続していないこともあります）
DMS ヒートマップのアノテーショントラックを作成する	[(r["position"], r["region"], r["is_core"], r.get("ss_element"))]
SAE ホットスポット特徴量をリガンド結合残基に絞り込む	region == "ligand" でクラスターをフィルタリングします
埋もれた残基と表面残基のシグナルを比較する	is_core ごとにグループ化して統計を取ります

解釈表

領域ラベル	生物学的な意味	一般的な機能上の役割
interface	相手鎖から distance_cutoff 以内	タンパク質間結合残基。変異によって複合体の形成が阻害されることがよくあります
ligand	リガンドの重原子から distance_cutoff 以内	ポケット残基。変異によって基質／補因子／薬剤の結合が阻害されることがよくあります
both	両方	アロステリック残基、または共有表面残基
other	どちらでもない	表面残基（is_core でない場合）またはコア残基（is_core の場合）。変異は安定性や遠隔効果を通じて影響します
is_core=true	RSA < core_rsa_cutoff（デフォルトは 0.25）	埋没残基。変異によってフォールドが不安定化することがよくあります

---

正直な制約事項

1. コンフォマーは 1 つのみです。静的な結晶構造では、別のコンフォメーションや誘導適合型の結合を捉えられません。ある残基が、あるコンフォマーではポケットにあっても、別のコンフォマーでは離れている場合があります。質問に合った結合状態の構造を選んでください。
2. 残基番号は不安定です。結晶構造用コンストラクトでは、N 末端タグが追加されたり、無秩序な N 末端／C 末端が省略されたりします。配列や別のアノテーションソースと結合する前に、必ず目印となる残基で確認してください。このスキルでは、気づきにくいオフセットを検出できません。
3. 距離のしきい値は慣例であり、絶対的なものではありません。文献でのデフォルト値は 5.0 Å です。ポケットの判定を厳密にするには 4.0 Å に下げ、2 次シェル残基を含めるには 6.0 Å に上げてください。
4. 小型または特殊な構造では、freesasa の RSA が 1.0 を超えることがあります。max-ASA の参照値は一般的なタンパク質環境を基準に調整されているためです。よくフォールドされた実際のタンパク質では、値は [0, 1.2] に集中します。値を割合として解釈しても問題ありませんが、極端な値は確認が必要な兆候として扱ってください。
5. partner_chains=[] も指定できますが、その場合、すべての dist_partner 値は null となり、界面解析は完全にスキップされます。
6. 対象は HETATM リガンドのみです。鎖内にすでに存在するリン酸化残基などの修飾残基は、リガンドとして検出されず、鎖の一部として扱われます。

---

相互参照

ツール	役割	用途
Structure_annotate_per_residue	このスキルの原子単位ツール	アノテーションそのもの
PDBeSIFTS_get_best_structures	UniProt → ランク付けされた PDB リスト	ステップ 1
PDBeSIFTS_get_all_structures	UniProt → PDB の全リスト	ステップ 1
RCSBAdvSearch_search_structures	RCSB のフリーテキスト検索	ステップ 1
UniProt_get_sequence_by_accession	正準配列	ステップ 3（残基番号の確認）
pdbe_get_entry_secondary_structure	SS のみ	ステップ 4 の代替手段
tooluniverse-residue-functional-mechanism-interpretation	下流の利用側	DMS ホットスポットを解釈する際に、このアノテーションを構造的なエビデンス層として使用します。このスキルでは、ステップ 7 でアノテーション付き DMS ヒートマップもプロットします