interpro-database

InterPro データベースへのアクセス

前提条件

1. uv：uv のスキルを読み、セットアップ手順に従って、uv がインストールされ PATH に設定されていることを確認してください。
2. ユーザーへの通知：.licenses/interpro_database_LICENSE.txt がワークスペースのルートディレクトリに存在しない場合は、（1）https://www.ebi.ac.uk/interpro/ および https://www.ebi.ac.uk/about/terms-of-use/ の利用規約を確認するようユーザーに目立つ形で通知し、（2）通知文とタイムスタンプを記録したファイルを作成してください。

概要

InterPro は、複数の多様なデータベースのシグネチャを単一の検索可能なリソースに統合し、冗長性を減らすとともに、ユーザーが配列解析結果を解釈しやすくします。これらのメンバーデータベース（Pfam、CDD、SMART など）を統合することで、InterPro はそれぞれの強みを生かし、強力な診断ツールおよび統合リソースを提供します。

interpro-database を使用すると、次のことができます。

• 特定のタンパク質に含まれるドメイン、ファミリー、部位を特定します。
• タンパク質の名称や機能が大きく異なる場合でも、タンパク質ファミリーに属する、または特定のドメインを含むタンパク質をすべて特定します。
• 特定のタンパク質ファミリーまたはドメインが見つかる種を調べます。
• タンパク質ファミリー情報および Gene Ontology（GO）用語を使ってゲノムに注釈を付けます。

このスキルには、InterPro API とシームレスに連携する堅牢なユーティリティ interpro_client.py が用意されています。レート制限（HTTP 429）、バックグラウンドクエリの待機時間追跡（HTTP 408）、終端エラー（HTTP 404/410）、遅延ページネーションをネイティブに処理します。

基本ルール

• ラッパーを使用する：データベースに直接アクセスするのではなく、データベースへのクエリには必ず scripts/interpro_client.py ヘルパースクリプトを実行してください。スクリプトは公正な利用を自動的に徹底し、再試行ロジックを実装しています。
• 探索的なクエリの場合：必ず厳密な --limit を指定して CLI を使用してください。これにより、コンテキストウィンドウを圧迫したり、数百万件もの結果を取得したりせずに、データスキーマをすばやく把握できます。
• ファイルへの出力：結果をすべてコンソールに表示しようとせず、CLI の --output を使ってファイルに出力してください。出力は jq またはコードを使って処理します。
• より複雑なパイプラインの場合は、モジュールを Python スクリプトに直接インポートしてジェネレーターを利用し、大規模なワークフローで CLI 文字列をデシリアライズする必要をなくしてください。
• 通知：このスキルを使用した場合は、その旨を出力に記載してください。

例：

uv run ./scripts/interpro_client.py fetch protein --source_db reviewed --limit 2 --query_params tax_id=9606 --output exploratory_results.jsonl

import sys
sys.path.append('scripts')
from interpro_client import fetch_interpro_data
import itertools

# fetch_interpro_data lazily yields results page-by-page
results = fetch_interpro_data(
    endpoint="entry",
    source_db="pfam",
    query_params={"page_size": 10}
)
for match in itertools.islice(results, 10):
    print(match["metadata"]["accession"])

エンドポイントの構築方法 4 種：

引数は、よく使われる 4 つの API パス構成に厳密に対応しています。独自に / 区切りの文字列を作成しないでください。

1. /{endpoint}（例：/entry）uv run ./scripts/interpro_client.py fetch entry --limit 10 --output entries.jsonl
2. /{endpoint}/{sourceDB}（例：/entry/pfam）uv run ./scripts/interpro_client.py fetch entry --source_db pfam --limit 10 --output pfam_entries.jsonl
3. /{endpoint}/{sourceDB}/{accession}（例：/entry/pfam/PF00001）uv run ./scripts/interpro_client.py fetch entry --source_db pfam --accession PF00001 --limit 10 --output pf00001_entry.jsonl
4. /{endpoint}/{sourceDB}/{linked_endpoint}/{sourceDB}/{accession}（例： /entry/interpro/protein/uniprot/P04637）uv run ./scripts/interpro_client.py fetch entry \ --source_db interpro \ --linked_endpoint protein \ --linked_source_db uniprot \ --linked_accession P04637 \ --limit 10 --output p04637_entries.jsonl

有効なソースデータベース（--source_db）

各エンドポイントで使用できる source_db の値は決まっています。無効な値を使用すると、404 エラーが返されます。

• /entry（16 個の値）：interpro、pfam、cathgene3d、ssf、 panther、cdd、profile、smart、ncbifam、prosite、prints、 hamap、pirsf、sfld、antifam。
• /protein（3 個の値）：uniprot（すべて）、reviewed（SwissProt）、 unreviewed（TrEMBL）。
• /structure（1 個の値）：pdb。
• /taxonomy（1 個の値）：uniprot。
• /proteome（1 個の値）：uniprot。
• /set（2 個の値）：pfam、cdd。

クイックリファレンス／主要なエンドポイントとパラメーター

すべてのクエリパラメーターを網羅した完全なリストについては、 完全な API リファレンスを参照してください。

API は完全に公開されており、主要なエンドポイントを 6 つサポートしています。上記で説明した相互にリンクされたパラメーターを使用して、これらを組み合わせることができます。各エンドポイントで使用できる具体的なクエリパラメーターを、以下に階層化して示します。

• /entry（ドメイン、ファミリー、活性部位、反復配列、または相同スーパーファミリーのエントリー）

  • integrated: 統合ステータスで絞り込みます（例：pfam）。
  • type: タイプで絞り込みます（例：family、domain、 homologous_superfamily）。
  • go_term / go_category: Gene Ontology で絞り込みます。
  • ida_search / ida_ignore / exact / ordered: ドメイン アーキテクチャで絞り込みます（IDA Search セクションを参照）。
  • extra_fields: 追加データを要求します（例：一致箇所の座標を示す counters）。
  • group_by / sort_by: 結果を集計または並べ替えます (有効な値は コンテキストによって異なります。完全な API リファレンスを参照してください)。
  • 例: uv run ./scripts/interpro_client.py count entry --source_db pfam --query_params type=domain --output count.jsonl

• /protein（エントリーまたはドメインに一致するタンパク質レコード）

  • tax_id: 分類 ID で絞り込みます（系統は検索しません）。
  • match_presence: InterPro の一致箇所があるタンパク質で絞り込みます （true／false）。
  • is_fragment: 完全な配列と断片配列で絞り込みます。
  • group_by: 結果を集計します（例：taxonomy）。
  • extra_fields: 配列または一致箇所の詳細を要求します。
  • isoforms / residues / structureinfo: 特定のサブ機能を含めます。
  • conservation / extra_features: 残基の保存性フラグまたは Mobidb／coil の機能を追加します (有効なのは /protein/{source_db}/{accession} のみです)。
  • 例: uv run ./scripts/interpro_client.py fetch protein --source_db uniprot --limit 20 --query_params tax_id=9606 --output human_proteins.jsonl

• /structure（InterPro エントリーにリンクされた PDB 構造）

  • experiment_type: 実験方法で絞り込みます（例：X-RAY DIFFRACTION）。
  • resolution: 解像度の上限で絞り込みます。
  • extra_fields: 構造に関する追加のメタデータを含めます。
  • group_by: 結果を集計します。
  • 例: ./scripts/interpro_client.py fetch structure --source_db pdb --accession 1ATP --limit 10 --output 1atp_structures.jsonl

• /taxonomy（分類分布ノード）

  • key_species: 主要な種に限定して絞り込みます。
  • with_names: 学名を含めます。
  • filter_by_entry / filter_by_entry_db: 特定のエントリーとの 共通部分で絞り込みます。
  • extra_fields: 分類に関する追加のメタデータを含めます。
  • 例: ./scripts/interpro_client.py fetch taxonomy --source_db uniprot --accession 9606 --limit 10 --output human_taxonomy.jsonl

• /proteome（InterPro にリンクされた完全なプロテオーム）

  • extra_fields: クエリを全般的に拡張します。
  • 例: uv run ./scripts/interpro_client.py fetch proteome --source_db uniprot --accession UP000005640 --limit 10 --output proteome.jsonl

• /set（関連するエントリーをまとめたキュレーション済みセット。例：Pfam クラン）

  • extra_fields: 追加のメタデータ (有効なのは /set/{sourceDB} のみです)。
  • 例: uv run ./scripts/interpro_client.py fetch set --source_db pfam --accession CL0001 --limit 10 --output pfam_clan.jsonl

InterPro ドメインアーキテクチャ（IDA）検索

InterPro は、ドメインアーキテクチャ（ドメインの正確な組み合わせと順序）を使ってタンパク質を検索するための強力なツールを提供しています。API では複数のドメインを指定してタンパク質を直接検索できないため（例：「PF00069 と PF00017 の両方を持つタンパク質を取得する」）、特定のドメインの組み合わせを持つタンパク質を見つけるには、2 段階の手順が必要です。

ステップ 1：一致するアーキテクチャを検索する（ida_search）

ida_search パラメーターはルート /entry エンドポイントで使用し、指定したドメインを含むすべての Domain Architecture（IDA）を検索します。

• 制約：
  • ルート /entry エンドポイントでのみ有効です。
  • IDA 以外のパラメーターと組み合わせることはできません。
• 修飾子（ida_search との組み合わせでのみ有効）：
  • ida_ignore：指定したドメインを検索対象から除外します（クエリパラメーター）。
  • ordered：ドメインが指定した順序どおりに並んでいることを保証します（フラグ）。
  • exact：アーキテクチャが完全に一致すること（追加のドメインがないこと）を保証します（フラグ）。ordered フラグが必要です。

例：キナーゼドメイン（PF00069）と SH2 ドメイン（PF00017）の両方を、この順序どおりに含むアーキテクチャを検索します。

uv run scripts/interpro_client.py fetch entry
  --query_params ida_search=PF00069,PF00017
  --flags ordered exact
  --output architectures.jsonl

注：返されるのはアーキテクチャとその一意な ida_id であり、個々のタンパク質すべてではありません。

ステップ 2：それらのアーキテクチャに対応するタンパク質を取得する（ida）

ステップ 1 で ida_id（例：619edbb...）を取得したら、/protein エンドポイントをフィルタリングして、その正確な構成を共有する実際のタンパク質をすべて取得できます。

制約：

• /protein および /entry/{sourceDB}/{accession} エンドポイントで有効です。

例：ステップ 1 で得られたアーキテクチャ ID のいずれかに一致するタンパク質を取得します。

uv run scripts/interpro_client.py fetch protein
  --source_db uniprot
  --query_params ida=619edbb2b445bfa3ad51bd894e3c115b025a5f25
  --output matching_proteins.jsonl

(パイプラインの構築や網羅的なクエリを行う場合は、ステップ 1 で得られたすべての ida_id を順番に処理し、それぞれについてステップ 2 を実行します。)

InterPro エントリーの種類

各 InterPro エントリーには種類が割り当てられており、タンパク質がそのエントリーに一致したときに推測できる内容を示します。

• ドメイン：さまざまな生物学的状況で存在する可能性のある、特徴的な機能、構造、または配列の単位です。例：PH ドメイン、古典的な C2H2 ジンクフィンガー。
• ファミリー：関連する機能、配列の類似性、または一次・二次・三次構造に共通の進化的起源が反映されているタンパク質のグループです。
• 相同スーパーファミリー：構造的な類似性に共通の進化的起源が反映されている一方で、配列の類似性が非常に低いことも多いタンパク質のグループです。通常、SUPERFAMILY および CATH-Gene3D データベースのシグネチャーで構成されます。
• リピート：タンパク質内で通常は繰り返される短い配列で、多くの場合、長さは 50 アミノ酸未満です。例：ロイシンリッチリピート、WD40 リピート。
• 部位：Active site（触媒活性に必要な保存残基を含む配列）および Binding site（タンパク質相互作用部位を形成する保存残基を含む配列）が含まれます。

InterPro-N の予測

InterPro-N は、標準の InterPro データベースを深層学習で拡張したものです。コンピュータービジョンに着想を得た AI アーキテクチャを使用し、タンパク質配列の注釈付けを「パノプティックセグメンテーション」タスクとして扱い、残基にラベルを付けてドメインを識別します。

InterPro-N を使用する場面

標準の InterPro シグネチャーは「ゴールドスタンダード」であり、InterPro-N の予測を優先して破棄すべきではありません。InterPro-N は主に、不足部分の補完や結果の精緻化に使用してください。

標準の InterPro に加えて使用する場合：

• 「ダークマター」（未特性化タンパク質）の解析：標準の InterPro でヒットがないタンパク質に使用します。InterPro-N は遠縁の相同タンパク質の特定に優れています。
• 複雑なリピートの解決：複数のタンデムリピート（例：TPR や WD40）を持ち、標準の HMM では結合されたり検出されなかったりする可能性のあるタンパク質に使用します。
• 不連続ドメインの予測：ドメイン配列が、まったく異なる挿入配列によって中断されている場合に使用します。

特定の状況で標準の InterPro の代わりに使用する場合：

• 境界の正確な特定：標準的な曖昧なヒットよりも、ドメインの開始位置と終了位置を正確に特定する必要がある場合に使用します。
• 大規模なメタゲノムスクリーニング：断片化された配列や大きく分岐した配列を対象に、初期段階で再現率の高いスクリーニングを行う場合に使用します。

フォールバック戦略：InterPro-N の確認

タンパク質のアノテーションを検索するよう依頼され、標準の InterPro クエリで結果やアノテーションが見つからない場合は、フォールバックとして 必ず InterPro-N を確認してください。

シナリオの例： ユーザーが「タンパク質 X の SSF アノテーションを列挙してください」と依頼し、標準クエリでヒットがなかった場合は、interpro_n フラグを指定してクエリを再実行してください。

このフォールバックは重要です。InterPro-N は、標準的な手法では見つからない「ダークマター」タンパク質の遠縁ホモログやドメインを特定できます。

見つかった場合は、これらのアノテーションが InterPro-N による深層学習の予測であることを、必ずユーザーに伝えてください。

使用方法

InterPro-N の予測には、uniprot をソースデータベースとして、protein エンドポイントに interpro_n フラグを指定してアクセスします。

CLI の場合：

uv run ./scripts/interpro_client.py fetch protein
    --source_db uniprot
    --accession A0A096LNN2
    --flags interpro_n
    --output A0A096LNN2_interpro_n.jsonl

Python パイプラインの場合：

results = fetch_interpro_data(
    endpoint="protein",
    source_db="uniprot",
    accession="A0A096LNN2",
    flags=["interpro_n"])

厳格な検索ルール

1. 常に UniProt アクセッションを使用し、遺伝子名は絶対に使用しない： InterPro でタンパク質を検索する際は、必ず UniProt アクセッション（例：P04637）を使用してください。InterPro は遺伝子名（例：TP53）をネイティブでサポートしておらず、確実にマッピングできるわけでもありません。ユーザーが遺伝子名を指定した場合は、まず Ensembl や UniProt などのデータベースを使ってアクセッションを特定してください。

2. カウントするために反復処理を絶対に行わない： 集計数（例：「ドメインはいくつありますか？」）を尋ねられた場合は、get_interpro_count() ヘルパーを使って、最初の API JSON レスポンスから count フィールドを必ず読み取ってください。要素を数えるために fetch_interpro_data ジェネレーターを反復処理することは絶対に避けてください。件数が 50,000 件を超えるエンドポイントを、カウントだけのために反復処理すると、エージェントが気づかないうちに停止し、API の不適切な使用にもなります。毎回です。例外はありません。

   ✅ 正しい例：

   CLI の場合：

   uv run ./scripts/interpro_client.py count entry
       --source_db interpro
       --query_params type=domain
       --output count.json
   

   Python パイプラインの場合：

   from interpro_client import get_interpro_count
   cnt = get_interpro_count(
       endpoint="entry",
       source_db="interpro",
       query_params={"type": "domain"},
   )
   

   ❌ 誤った例（fetch の反復処理）：

   # 絶対に実行しないこと：
   uv run ./scripts/interpro_client.py fetch entry
       --source_db interpro
       --query_params type=domain
       --output output.jsonl
       && wc -l output.jsonl
   

すぐに使える例

各種エンドポイントの呼び出し方法と、返される JSON 出力スキーマの詳しい例については、 レスポンス例のリファレンスを参照してください。 この TSV には、コマンドラインの呼び出し、Python での同等の処理、対応する JSON ペイロード構造が含まれています。

1. すべてのタンパク質ドメインを特定する

# Fetches InterPro Entries within UniProt protein P04637
# URL equivalent: /entry/interpro/protein/uniprot/P04637
uv run ./scripts/interpro_client.py fetch entry
    --source_db interpro
    --linked_endpoint protein
    --linked_source_db uniprot
    --linked_accession P04637
    --output p04637_domains.jsonl

2. Entry のすべての PDB 構造を取得する

# URL equivalent: /structure/pdb/entry/interpro/IPR011615
# Only fetch the first 5 structures
uv run ./scripts/interpro_client.py fetch structure
    --source_db pdb
    --linked_endpoint entry
    --linked_source_db interpro
    --linked_accession IPR011615
    --output ipr011615_structures.jsonl