ncbi-sequence-fetch

NCBI Sequence Fetch

前提条件

1. uv：uv のスキルを読み、セットアップの手順に従って、uv がインストールされ、PATH に含まれていることを確認してください。
2. ユーザーへの通知：.licenses/ncbi_sequence_fetch_LICENSE.txt がワークスペースのルートディレクトリにまだ存在しない場合は、まず（1）https://www.ncbi.nlm.nih.gov/ および https://www.ncbi.nlm.nih.gov/home/about/policies/ の利用条件を確認するようユーザーに目立つ形で通知し、次に（2）通知文とタイムスタンプを記録したファイルを作成してください。
3. .env ファイル：ホームディレクトリに .env ファイルがあることを確認してください。存在しない場合は作成してください。
4. NCBI_API_KEY（任意）：NCBI のレート制限が毎秒 3 リクエストから 10 リクエストに引き上げられます。このスキルはキーがなくても動作しますが、多数のクエリを実行する予定がある場合や 429 エラーが発生した場合は、キーの使用を推奨します。キーは https://www.ncbi.nlm.nih.gov/account/settings/ で無料登録できます。このスキルがユーザーのリクエストに関連すると思われる場合は、credentials スキルの安全な認証情報プロトコルを使用して、このキーの有無を確認し、必要に応じて要求しなければなりません。

基本ルール

• ラッパーを使用する：データベースに直接アクセスするのではなく、必ず提供されたヘルパースクリプトを実行してデータベースにクエリしてください。スクリプトが必要なレート制限を適切に自動適用します。
• API キーのサポート：ユーザーの環境に NCBI_API_KEY が設定されている場合、クエリの速度制限は自動的に大幅に引き上げられます。
• 通知：このスキルを使用した場合は、その旨を出力に記載してください。

概要

NCBI の Entrez E-utilities（efetch、esearch、elink、esummary）をラップし、タンパク質およびヌクレオチド配列を取得します。配列取得ワークフロー全般を網羅する 10 個のサブコマンドを提供します。

• fetch-protein — アクセッションによるタンパク質の直接検索（GenPept、RefSeq）
• fetch-nucleotide — アクセッションによるヌクレオチドの直接検索
• cds-translate — CDS を取得してタンパク質に翻訳（3 つの方法）
• search — NCBI の任意のデータベースを全文検索
• elink — データベース間のリンクをたどる（PubMed→Protein など）
• gene-protein — 遺伝子名と生物種でタンパク質を検索
• locus-protein — Locus タグと生物種でタンパク質を検索
• pubmed-proteins — PubMed 論文に関連付けられたタンパク質を検索
• patent-search — 特許からタンパク質配列を抽出
• organism-length — 最終手段として、生物種と正確なアミノ酸長で検索

ユーティリティスクリプト

scripts/ncbi_fetch.py — サブコマンドを備えた単一のスクリプトです。

すべてのサブコマンドは、構造化された JSON 出力を書き込みます。--output FILE を使用してファイルに保存するか、省略して標準出力に表示します。人が読みやすい要約は常に標準出力に表示されます。

1. アクセッションでタンパク質を取得

アクセッション（XP_、NP_、GenPept など）を指定して、NCBI からタンパク質 FASTA を取得します。

uv run scripts/ncbi_fetch.py fetch-protein XP_022033624 -o /tmp/result.json
uv run scripts/ncbi_fetch.py fetch-protein NP_001234567 ABC12345.1

2. アクセッションでヌクレオチドを取得

アクセッションを指定して、NCBI からヌクレオチド FASTA を取得します。

uv run scripts/ncbi_fetch.py fetch-nucleotide MK034466 -o /tmp/result.json

3. CDS の翻訳

CDS／ヌクレオチドのアクセッションを取得し、タンパク質配列に翻訳します。次の 3 つの方法を順に試します：1. NCBI があらかじめ翻訳した CDS タンパク質（fasta_cds_aa）

2. GenBank XML の CDS アノテーション翻訳 3. 生のヌクレオチド → 6 フレーム ORF 検出

uv run scripts/ncbi_fetch.py cds-translate MK034466 -o /tmp/result.json
uv run scripts/ncbi_fetch.py cds-translate HQ662330 --target-length 1043

アクセッションがゲノムレコード（mRNA／CDS ではない）の場合、ツールは is_genomic: true を報告するため、代わりに相同性に基づくアプローチを使用できます。

4. 任意のデータベースを検索

Entrez のクエリ構文を使用して全文検索します。すべての NCBI データベースに対応しています。

# Search protein database
uv run scripts/ncbi_fetch.py search "WRR4B[Gene Name] AND Arabidopsis[Organism]" \
  --database protein --retmax 5 --fetch-sequences

# Search nucleotide database
uv run scripts/ncbi_fetch.py search "Rz2[Gene Name] AND Beta vulgaris[Organism]" \
  --database nuccore --retmax 10

# Search with patent filter
uv run scripts/ncbi_fetch.py search "disease resistance AND Solanum[Organism] AND patent[Properties]" \
  --database protein --fetch-sequences

# Search by sequence length
uv run scripts/ncbi_fetch.py search '"Oryza sativa"[Organism] AND 1043[SLEN]' \
  --database protein --fetch-sequences --retmax 50

5. データベース間リンク（elink）

NCBI のデータベース間リンクをたどります（例：PubMed 論文 → 関連するタンパク質）。

uv run scripts/ncbi_fetch.py elink 24896089 --dbfrom pubmed --db protein \
  --fetch-sequences -o /tmp/linked.json

6. 遺伝子名と生物種で検索

遺伝子名と生物種を指定して、タンパク質配列を検索します。[Gene Name] および [Organism] 修飾子を使って NCBI Protein を検索します。

uv run scripts/ncbi_fetch.py gene-protein WRR4B --organism "Arabidopsis thaliana"
uv run scripts/ncbi_fetch.py gene-protein Pikh-2 --organism "Oryza sativa" \
  --target-length 1043 -o /tmp/result.json

7. Locus タグで検索

NCBI Protein と Nuccore の両方のデータベースで Locus タグを検索します。タンパク質への直接のヒットがない場合は、GenBank XML から CDS 翻訳を抽出します。

uv run scripts/ncbi_fetch.py locus-protein At1g56540 --organism "Arabidopsis thaliana"
uv run scripts/ncbi_fetch.py locus-protein Niben101Scf02422g02015.1 \
  --organism "Nicotiana benthamiana" -o /tmp/result.json

8. PubMed リンクタンパク質

PubMed 論文に関連付けられたタンパク質配列を検索します。PMID で NCBI Protein を検索し、 elink PubMed→Protein をたどって、リンク先の Nuccore レコードから CDS 翻訳配列を抽出します。

uv run scripts/ncbi_fetch.py pubmed-proteins 30692254 --identifier WRR4B
uv run scripts/ncbi_fetch.py pubmed-proteins 24896089 --identifier "K2" \
  -o /tmp/result.json

9. 特許配列検索

2 つのモードがあります。

特許番号で検索 — 特定の特許からすべてのタンパク質配列を取得します。 bash uv run scripts/ncbi_fetch.py patent-search --patent-number US10123456 -o /tmp/patent.json

キーワードで検索 — patent[Properties] フィルターを使用して NCBI Protein を検索します。 bash uv run scripts/ncbi_fetch.py patent-search --keywords WRR4B Albugo --organism "Arabidopsis thaliana" -o /tmp/patent.json

重要

特許の慣例：分子生物学の特許では、SEQ ID NO: 1 は通常 DNA 配列であり、SEQ ID NO: 2 は主要なタンパク質です。番号がそれより大きい SEQ ID NO は、変異体または関連配列です。対象とする主要なタンパク質を選ぶ際は、Sequence 2 を優先してください。

10. 生物種＋長さで検索

生物種と予想されるタンパク質の長さしかわからない場合の最終手段となる検索です。 NCBI の [SLEN] フィルターを使って、長さが完全に一致する配列を検索します。

uv run scripts/ncbi_fetch.py organism-length \
  --organism "Arabidopsis thaliana" --length 1048 --retmax 50 \
  -o /tmp/result.json

メモ

複数の候補が返されることがよくあります。JSON 出力のヘッダーを使って、正しいタンパク質を特定してください。

ワークフロー

標準的な配列取得の優先順位

タンパク質配列を見つける際は、次の優先順位に従ってください。

1. 直接アクセッション — GenPept／RefSeq アクセッションを指定して fetch-protein を実行
2. CDS 翻訳 — ヌクレオチド／CDS アクセッションを指定して cds-translate を実行
3. PubMed リンク — PMID と遺伝子名を指定して pubmed-proteins を実行
4. 遺伝子座の検索 — 遺伝子座タグと生物種を指定して locus-protein を実行
5. 遺伝子名＋生物種 — 遺伝子名と生物種を指定して gene-protein を実行
6. 特許検索 — 特許番号またはキーワードを指定して patent-search を実行
7. 生物種＋長さ — 最終手段として organism-length を実行

結果の解釈

• すべてのサブコマンドは、results 配列を含む JSON を返します
• 各結果には sequence（アミノ酸配列）、length、および header／メタデータが含まれます
• 複数の結果が返された場合は、次の基準で選択します。
  • 予想される長さ（target_length）に最も近いもの
  • ヘッダーの関連性（遺伝子名や「病害抵抗性」を示すキーワードとの一致）
  • ソースの優先順位（RefSeq > GenPept > 特許）

リファレンス

• NCBI E-utilities のドキュメント：https://www.ncbi.nlm.nih.gov/books/NBK25499/
• Entrez の検索構文：https://www.ncbi.nlm.nih.gov/books/NBK49540/
• データベース一覧：protein、nuccore、gene、pubmed、pmc、biosample など
• 一般的なアクセッション形式：
  • XP_／NP_ — NCBI RefSeq タンパク質
  • AAA から AZZ と数字 — GenPept（翻訳済み GenBank）
  • MK、MN、HQ などと数字 — GenBank ヌクレオチド
  • ENSG、ENST、ENSP — Ensembl（代わりに ensembl-database スキルを使用してください）
  • Q、P、O と数字 — UniProt（代わりに uniprot-database スキルを使用してください）