ensembl-database

Ensembl データベース：ID マッピングとゲノム特徴

前提条件

1. uv：uv スキルを読み、そのセットアップ手順に従って、 uv がインストールされ、PATH に設定されていることを確認してください。
2. ユーザーへの通知：ワークスペースのルートディレクトリに .licenses/ensembl_database_LICENSE.txt がまだ存在しない場合は、（1）ユーザーに https://useast.ensembl.org/index.html と https://github.com/Ensembl/ensembl-rest/wiki の利用条件を確認するよう目立つ形で通知し、（2）通知文とタイムスタンプを記録したファイルを作成してください。

概要

Ensembl データベースは、ゲノムアノテーションのためのリソースです。このスキルを使うと、 Ensembl REST API を利用して、曖昧なシンボルの解決、 ID（RefSeq、HGNC、UniProt、ENSG）の相互参照、未加工配列の取得、 詳細な転写産物構造の取得ができます。

主な概念：

• ENSG（遺伝子）： ヒト遺伝子の安定した識別子です。他の種では、 異なる3文字の種コードが使われます。
• ENST（転写産物）： 転写産物（スプライシングアイソフォーム）の 安定した識別子です。
• ENSP（タンパク質）： 翻訳されたタンパク質の安定した識別子です。
• MANE Select： Ensembl と NCBI が合意したコンセンサスの主要転写産物です。
• Canonical： Ensembl の代表的な転写産物です（MANE が利用できない場合、またはヒト以外の場合に使用します）。

基本ルール

• ラッパーを使用する： データベースに直接アクセスするのではなく、必ず用意されているヘルパースクリプトを実行して データベースを照会してください。スクリプトが必要なレート制限を 自動的に適切に適用します。
• デフォルトの種： プロンプト内で種が指定されていない、または曖昧な場合は、 "human" をデフォルトにします。このデフォルト設定をユーザーが認識できるよう、 必ず明示してください。
• 主要転写産物： 遺伝子の転写産物を一覧表示する場合、ユーザーがすべての代替アイソフォームを明示的に求めない限り、 MANE Select 転写産物（ヒトの場合）または Canonical 転写産物（その他の場合）のみを返してください。 複数の転写産物が利用可能で、主要なものをデフォルトにする場合は、必ずユーザーに伝えてください。
• アセンブリの扱い： デフォルトのアセンブリは GRCh38 です。GRCh37 のリクエストでは、 --assembly GRCh37 フラグを必ず使用してください。デフォルト以外のアセンブリを使用する場合は、必ずユーザーに伝えてください。
• 出力先： スクリプトは、デフォルトでは完全な JSON/FASTA 出力を /tmp 内の一時ファイルに書き込みます。 また、--output フラグを使用してユーザー指定のファイルに出力することもできます。 さらに、簡潔な要約を stdout に出力します。
• 通知： このスキルを使用した場合は、その旨を出力に記載してください。

利用可能なコマンド

1. Gene ID の解決 — シンボル、別名、または RefSeq ID を ENSG ID に解決します。 主要シンボルが見つからない場合は、同義語の解決に自動的にフォールバックします。

uv run scripts/ensembl_api.py resolve-gene TP53 --species human --output tp53.json
uv run scripts/ensembl_api.py resolve-gene PCL2 --output pcl2.json # Falls back to synonym resolution

2. ID を外部データベースにマッピング — Ensembl ID を UniProt、 HGNC、RefSeq などと相互参照します。

uv run scripts/ensembl_api.py map-id ENSG00000141510 --external-db UniProt --output uniprot_map.json
uv run scripts/ensembl_api.py map-id ENST00000269305 --external-db RefSeq_mRNA --output refseq_map.json

3. ゲノム配列の取得 — 座標範囲の生 DNA 配列を取得します。--assembly GRCh37 を指定すると GRCh37 に対応します。

uv run scripts/ensembl_api.py get-sequence 17:7661779-7687550 --species human --output seq.txt
uv run scripts/ensembl_api.py get-sequence chr9:21971100-21971200 --assembly GRCh37 --output seq_grch37.txt

4. 遺伝子の概要 — シンボル、バイオタイプ、説明、 染色体上の位置などのメタデータを表示します。

uv run scripts/ensembl_api.py gene-summary ENSG00000141510 --output gene_summary.json

5. 転写産物の一覧表示 — 遺伝子の全転写産物を表示します。--only-mane または --only-canonical フィルターを指定できます。出力には転写産物サポートレベル（TSL）が含まれます。

uv run scripts/ensembl_api.py transcripts ENSG00000141510 --only-mane --output transcripts_mane.json
uv run scripts/ensembl_api.py transcripts ENSG00000141510 --only-canonical --output transcripts_canonical.json
uv run scripts/ensembl_api.py transcripts ENSG00000141510 --output transcripts_all.json

5b. Canonical TSS — 遺伝子の canonical transcript の転写開始 部位（TSS）の単一座標を取得します。

メモ

標準の transcripts コマンドと異なり、canonical-tss は シンボル（例：TP53）と Ensembl ID の両方を受け付け、自動的に解決します。 また、鎖の向きを考慮して計算します（TSS は + 鎖では Start、 - 鎖では End です）。単一の整数座標を直接出力します。

uv run scripts/ensembl_api.py canonical-tss TP53 --output tp53_tss.json
uv run scripts/ensembl_api.py canonical-tss ENSG00000141510 --output tss.json

6. 転写産物の構造 — 転写産物のエクソン座標、CDS 境界、および計算された 5'/3' UTR 領域を表示します。

uv run scripts/ensembl_api.py transcript-structure ENST00000269305 --output structure.json

7. タンパク質情報 — 転写産物の ENSP ID と配列長を表示します。

uv run scripts/ensembl_api.py protein-info ENST00000269305 --output protein_info.json

8. タンパク質配列 — 転写産物（ENST）またはタンパク質 （ENSP）ID のアミノ酸 FASTA を取得します。

uv run scripts/ensembl_api.py protein-sequence ENST00000269305 --output protein.fasta
uv run scripts/ensembl_api.py protein-sequence ENSP00000269305 --output protein_ensp.fasta

9. バリアントの影響（VEP） — ゲノムバリアントの分子的影響を予測します。オープンライセンスのプラグインとして、AlphaMissense、Conservation、 DosageSensitivity、IntAct、MaveDB、OpenTargets、LoF（Loftee）、NMD、UTRAnnotator、 mutfunc、LOEUF に対応しています。

uv run scripts/ensembl_api.py vep 9:21971147:T:C --species human --output vep.json
uv run scripts/ensembl_api.py vep rs699 --species human --output vep_rs699.json

VEP の標準出力の例：

[*] Variant: 9:21971147:T>C
[*] Most severe consequence: missense_variant
[*] Found 15 transcript consequences.

[*] VEP Predictions:

  - ENST00000304494 (CDKN2A): Consequence = missense_variant
  - ENST00000304494 (CDKN2A): Amino Acids = N/S
  - ENST00000304494 (CDKN2A): SIFT = deleterious (0.01)
  - ENST00000304494 (CDKN2A): AlphaMissense Class = likely_benign
  - ENST00000304494 (CDKN2A): AlphaMissense Pathogenicity = 0.2129
  - ENST00000304494 (CDKN2A): Conservation = 2.05
  - ENST00000304494 (CDKN2A): Dosage Sensitivity (Haplo) = 0.889228328567991
  - ENST00000304494 (CDKN2A): Dosage Sensitivity (Triplo) = 0.135514349094646
  - ENST00000304494 (CDKN2A): Loss of Function (LOEUF) = 0.791

VEP 結果の提示： VEP コマンドの実行後、標準出力にある VEP 予測の一覧を、必ずすべてユーザーに提示してください。この一覧には、標準的な VEP 予測（Consequence、Amino Acids、SIFT、PolyPhen）と オープンライセンスのプラグイン結果（AlphaMissense、Conservation、Dosage Sensitivity、 LOEUF、Loftee LoF、NMD、UTRAnnotator、Mutfunc）の両方が含まれます。要約だけで済ませず、ユーザーがすべての予測を確認できるよう、一覧を完全な形で示してください。一覧が非常に長い （転写産物が多数ある）場合は、MANE Select／canonical transcript の行をすべて表示し、 完全なデータは JSON 出力に含まれていることを明記してください。

出力の解析

標準出力に要約されていない、詳細なネスト構造データ（転写産物の Exon 2 の正確な整数 座標など）が必要な場合：

1. JSON ファイルを特定します（--output で指定されたファイル、またはスクリプトが出力した一時ファイルのパス）。
2. jq などのターミナルツールを使用するか、使い捨ての短い Python スニペットを書いて、要求されたデータ項目を抽出します。非常に大きな JSON ファイル全体をコンテキストに読み込もうとしないでください。

カスタムクエリ

スクリプトがサポートしていない API 呼び出し（例：タンパク質ドメインのアノテーションの取得、アセンブリ間の座標マッピング、相同性検索、連鎖不平衡、表現型の検索）が必要な場合は、 利用可能なエンドポイント、パラメーター、レスポンスフィールドの完全なリファレンスとして references/ensembl_rest_api_reference.md を参照してください。

重要： カスタムスクリプトを作成する場合や、提供されたスクリプトの代替手段を使用する場合は、Ensembl REST API のレート制限（1 秒あたり最大 15 リクエスト）を必ず守り、429 Too Many Requests エラーに適切に対処してください（例：指数バックオフを使用する）。