uniprot-database

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

前提条件

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

概要

UniProt ナレッジベース（UniProtKB）、非冗長配列アーカイブ（UniParc）、およびクラスター化された配列セット（UniRef）への直接的なプログラムアクセスを提供します。このスキルを使用すると、タンパク質の探索、相互参照、キュレーション済みの生物学的データの取得、低レベルのデータベース照会を行えます。

基本ルール

• ラッパーの使用：独自に curl リクエストを構築するのではなく、必ず提供された Python スクリプト（例：scripts/uniprot_tools.py）を使用してください。
• 幻覚の禁止：タンパク質の機能、メタデータ、配列をでっち上げてはいけません。このスキルのサービスで対応できるタスクでは、必ずツールの出力のみを根拠としてください。
• 通知：このスキルを使用した場合は、その旨を出力に記載してください。

使用例

• タンパク質の機能を検索：機能アノテーション、GO 用語、細胞内局在などを照会します。
• タンパク質配列を検索：UniProtKB、UniParc、UniRef で、機能アノテーションや遺伝子などを基にタンパク質配列を検索します。
• タンパク質と生物種の関係を把握：分類データベースとプロテオームセットを活用します。
• 大規模なメタデータを取得：ストリーミングを介して、数千のタンパク質のアノテーションを取得します。
• 配列を探索：UniParc を介してオルソログやモデル生物以外のタンパク質を見つけます。
• ID マッピング：UniProt と 100 以上の外部データベース間で ID を変換します。
• 履歴データ（UniSave）：エントリーの以前のバージョンを取得したり、削除された配列を追跡したりします。

利用可能なツール

タスクの種類とデータ量に応じて、適切なツールを選択してください。

• get：特定のエントリーのメタデータと配列を取得します。既知のアクセッションが1つだけある場合に最適です。
  • UniSave の履歴データにもアクセスできます（--dataset unisave を使用）。以前のリリースのデータを照合したり、以前は有効だったアクセッションが検索結果に表示されなくなった理由を特定したりする際に不可欠です。
• search：クエリに一致するエントリーを検索します。探索や発見に最適です。
  • 大規模なダウンロードを開始する前に、クエリが想定どおりのタンパク質を返すか確認するには、--limit 5 を指定してください。
  • 結果が500件を超えると、自動的にページネーションを行い、安定したダウンロードを提供します。
  • 警告：ページネーションを伴う検索では、TXT などの形式は --limit を指定しても信頼できません。これはエントリー数ではなく行数に適用されるためです。
  • 検索クエリフィールドのドキュメントを参照してください。
• stream：一致するすべてのエントリーをストリーミングします。大規模なデータセット（最大10,000,000件）の一括取得に最適です。
  • --limit はサポートしていません。常に結果セット全体を返します。
  • 一部の結果だけが必要な場合は、search に --limit を指定してください。
• count：クエリに一致するエントリー数を数えます。件数に関する直接的な質問への回答や、全件を対象とした search または stream を実行する前の初期見積もりに最適です。
• sparql：複雑な探索のためにグラフクエリを実行します。件数のカウント、配列の完全一致検索、複数データベースにまたがるクエリに最適です。
  • SPARQL の例を参照してください。
• map：UniProt と100以上のデータベースとの間でIDを変換します。IDマッピングのタスクに最適です。
  • IDマッピングのドキュメントを参照してください。
  • search と map の使い分け：ユーザーから明示的に依頼されていない場合は、map を使う前にまず search を試してください。たとえば、外部IDが UniParc では検索できても、UniProtKB へのマッピングに失敗する場合があります。

ワークフロー

一般的なタンパク質研究のワークフロー

このチェックリストをコピーして、進捗を記録してください。

• ステップ1：対象のタンパク質と生物種を特定します。
• ステップ2：UniProtKB でレビュー済みエントリー（reviewed:true）を検索します。
• ステップ3：レビュー済みエントリーが見つからない場合は、未レビューのエントリーを検索するか、UniParc を使って配列を探します。
• ステップ4：必要に応じて、外部ID（Ensembl、PDB など）を UniProt アクセッションにマッピングします。
• ステップ5：希望する形式（JSON、FASTA）で機能メタデータまたは配列を取得します。

検索で見つからない場合の対応（非モデル生物の遺伝子検索など）

直接クエリ（例：gene:SYMBOL）で見つからない場合：

1. タンパク質名で検索する：一般的なタンパク質名で検索します（例：protein_name:Alpha-crystallin A）。
2. UniParc を使う：UniProtKB で完全に注釈付けされていない場合でも、あらゆる生物由来の配列を統合している UniParc データセットを検索します。
3. オーソログ／標準名を確認する：まずヒト／マウスのオーソログを特定し、正しい名称またはメモニックを確認します。

一括取得の優先順位

重要

一括データには、常に stream または sparql を優先してください。 search は探索に適しています。結果が500件を超えると、自動的にページネーションを行い、安定したダウンロードを提供します。

• 優先度0：count：search または stream を実行する前に、必ず結果件数を確認してください。
• 優先度1：stream：一括データ取得の主要な方法です（最大10M件）。--limit はサポートしておらず、常にすべての結果を返します。
• 優先度2：sparql：取得時の複雑なフィルタリングや完全一致検索に最適です。

配列ベースの検索（完全一致）

重要

タンパク質を完全なアミノ酸配列で検索する場合は、SPARQL を使用してください。REST API の /search エンドポイントは、配列文字列による直接検索をサポートしていません。完全一致以外の検索には、専用の配列類似性検索スキルを使用してください。UniProt でクエリが見つからない場合は、UniParc を使用してください。

SPARQL クエリパターン（UniProt）：

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
SELECT ?protein ?name WHERE {
  ?protein a up:Protein ;
           up:sequence/rdf:value "SEQUENCE_HERE" .
  OPTIONAL {
    ?protein up:recommendedName/up:fullName ?name .
  }
}

SPARQL クエリパターン（UniParc）：

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

SELECT ?uniparc ?val WHERE {
  GRAPH <http://sparql.uniprot.org/uniparc> {
    ?uniparc a up:Sequence ;
             rdf:value ?val .
    FILTER (?val = "SEQUENCE_HERE")
  }
}

エントリー数を効率的にカウントする

重要

エントリー数をカウントする場合（例：「ヒトのタンパク質はいくつありますか？」）は、count または SPARQL を使用してください。

カウントパターン（生物種ごとのタンパク質数）：

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX taxon: <http://purl.uniprot.org/taxonomy/>
SELECT (COUNT(?protein) AS ?count) WHERE {
  ?protein a up:Protein ;
           up:reviewed true ;
           up:organism taxon:9606 .
}

REST 検索の構文

• リスト内にカンマを使用しない：カンマはリテラルとして扱われます。項目を区切るには、大文字の OR を使用してください。
  • グループ化：accession:(P12345 OR P67890)
  • 繰り返し：accession:P12345 OR accession:P67890
• スペース = AND：例：gene:p53 human は両方を検索します。

コマンドの例

以下は、uniprot_tools.py の各モードのコマンド例です。

指定したクエリに一致するエントリーの総数をカウントします。

uv run scripts/uniprot_tools.py count "taxonomy_id:9606"

エントリーを検索します。

uv run scripts/uniprot_tools.py search "gene:p53 AND reviewed:true" --limit 5

アクセッションを指定して単一のエントリーを取得します。

uv run scripts/uniprot_tools.py get P04637

過去または削除済みのエントリーを取得します（UniSave）。

uv run scripts/uniprot_tools.py get P04637 --dataset unisave

大量の結果セットをストリーミングして一括取得します（一致するすべてのエントリーを返します。--limit はサポートされていません）。

uv run scripts/uniprot_tools.py stream "taxonomy_id:9606 AND reviewed:true" --format tsv --fields accession,gene_names > human_reviewed.tsv

あるデータベースの ID を別のデータベースの ID にマッピングします。

uv run scripts/uniprot_tools.py map "P04637" --from_db UniProtKB_AC-ID --to_db Gene_Name

SPARQL でグラフクエリを実行します。

uv run scripts/uniprot_tools.py sparql 'PREFIX up: <http://purl.uniprot.org/core/> SELECT ?protein WHERE { ?protein a up:Protein ; up:reviewed true . } LIMIT 5'

よくある間違い

• name: を使い、protein_name: を使わない：name: はサポートされている クエリ用語ではありません。代わりに protein_name: を使用してください。
• UniParc を無視する：モデル生物以外の生物は、UniParc にしか存在しない場合があります。
• アクセッションと UPI を混同する：UniProtKB アクセッション（例：P04637）は 機能に関するメタデータに関連付けられています。UniParc ID（UPI...）は配列 のみを対象とします。ID Mapping ツールを使うと、UniParc ID から UniProtKB アクセッションへの 相互参照を確認できます。
• ID Mapping のターゲットに UniProtKB-AC を使う：代わりに UniProtKB を使用してください。
• 複雑なクエリをあきらめる：複雑な検索クエリが失敗した場合は、あきらめずに SPARQL を使用してみてください。
• ID の意味を確認せずに使用する：ID（例：キーワード、GO 用語、Pfam ID など）の意味を 知っていると決して思い込まないでください。検索に使う前に、必ず UniProt で ID の 自然言語による説明や意味を調べ、意図した検索語と一致することを確認してください。
• 広範な検索で引用情報によるノイズを無視する：広範なテキスト検索（search "term"）では、UniProt が論文タイトルを含むメタデータ全体を検索するため、 偽陽性（例：一般的な維持タンパク質）が頻繁に返されます。機能の調査には、 cc_function: や protein_name: など、フィールドを指定したフィルターを必ず優先してください。
• 短い検索語を引用符で囲み忘れる：引用符で囲んでいない短い検索語（例： lanM）は、生物名（例：Lancefieldella）など、ほかのフィールド内の部分文字列に 一致する場合があります。引用符とフィールド接頭辞（例：gene:lanM）を使って、 正確な一致を絞り込んでください。
• タンパク質配列を直接操作する：配列に関する操作には、必ずコードとツールを使用してください。 タンパク質配列を手作業で編集、切り詰め、変更しないでください。
• 大量データの取得に検索を使いすぎる：stream または sparql で処理できる場合、 数百万件のエントリーを取得するために search を使用しないでください。非常に大きな データセットでは、ストリーミングのほうが効率的です。なお、stream には出力数の ハードリミット 10,000,000 があり、--limit はサポートされていません。
• データ量の確認を忘れる：--limit なしで search を実行する前、または stream を使う前には、必ず count を実行してください。無制限のクエリでは、 数百万件が返される場合、完了までに時間がかかり、大量のリソースを消費する可能性があります。
• stream で --limit を使う：stream コマンドは --limit をサポートしていません。 件数を制限した結果が必要な場合は、search と --limit を使用してください。
• ライセンスに関する注意書きを忘れる：UniProt のデータを含む結果を初めて 提示する際は、UniProt Database を使用したことを明記し、ライセンス条項を確認するよう ユーザーに案内してください。タスクが簡潔な場合でも、UniProt のデータを含む最初の回答には この帰属表示が必要です。

参考資料

• SPARQL の例
• 検索クエリフィールドのドキュメント
• ID Mapping のドキュメント
• UniProt エビデンスのドキュメント
• 基盤となる API エンドポイント（scripts/uniprot_tools.py が使用）：
  • get、search、stream、count -> rest.uniprot.org/{dataset}/
  • map -> rest.uniprot.org/idmapping/
  • sparql -> sparql.uniprot.org/sparql
  • get --dataset unisave -> rest.uniprot.org/unisave/