alterlab-ensembl

Ensembl Database

概要

EMBL-EBI が管理する、脊椎動物のゲノムデータを網羅したリソースである Ensembl ゲノムデータベースにアクセスして、データを照会します。このデータベースは、250 種を超える種の遺伝子アノテーション、配列、バリアント、制御情報、比較ゲノムデータを提供します。従来の REST API はリリース 116（2026 年 6 月 9 日リリース。GET /info/software → {"release": 116}）を提供します。

ご注意（2026-09-23 に確認）： リリース 116 は、従来のプラットフォームにおける最終リリースです。https://rest.ensembl.org（および grch37.rest.ensembl.org）は、終了日の発表がないまま引き続き稼働しますが、データは今後更新されません。従来のウェブサイトはアーカイブ https://jun2026.archive.ensembl.org として引き続き利用できます。新しいデータは、現在、新しい Ensembl プラットフォーム https://www.ensembl.org（以前の beta.ensembl.org、5,200 以上のゲノム）に公開されており、プログラムからのアクセスには GraphQL（POST https://www.ensembl.org/data/graphql）と、配列用の GA4GH refget を使用します。ここで説明する REST API は引き続き動作し、GRCh38／GRCh37 のヒト関連作業に最も簡単に利用できます。リリース 116 以降に追加されたゲノムやアノテーションの更新には GraphQL を使用し、長期運用するパイプラインでは移行を計画してください。

このスキルを使用する場面

以下の場合にこのスキルを使用してください。

• シンボルまたは Ensembl ID で遺伝子情報を照会する
• DNA、転写産物、またはタンパク質の配列を取得する
• Variant Effect Predictor（VEP）を使用して遺伝的バリアントを解析する
• 種をまたいでオーソログやパラログを探す
• 制御領域やゲノムアノテーションにアクセスする
• ゲノムアセンブリ間（例：GRCh37 から GRCh38）で座標を変換する
• 比較ゲノム解析を実行する
• Ensembl のデータをゲノム研究のパイプラインに統合する

該当しない場合

シナリオ	代わりに使用
NCBI Gene レコード、RefSeq アクセッション、Entrez 遺伝子 ID	alterlab-gene-db
集団アレル頻度／制約（gnomAD v4）	alterlab-gnomad
バリアントの臨床的意義（ClinVar）	alterlab-clinvar
ENA／SRA アクセッションによる生リードまたはアセンブリ	alterlab-ena
CLI から簡単なコマンドで遺伝子を検索する	alterlab-gget

主な機能

1. 遺伝子情報の取得

シンボル、Ensembl ID、または外部データベース識別子で遺伝子データを照会します。

一般的な操作：

• シンボルで遺伝子情報を検索する（例：「BRCA2」、「TP53」）
• 転写産物とタンパク質の情報を取得する
• 遺伝子の座標と染色体上の位置を取得する
• 外部データベース（UniProt、RefSeq など）への相互参照にアクセスする

ensembl_rest パッケージを使用する場合：

from ensembl_rest import EnsemblClient

client = EnsemblClient()

# Look up gene by symbol
gene_data = client.symbol_lookup(
    species='human',
    symbol='BRCA2'
)

# Get detailed gene information (method is lookup, NOT lookup_id)
gene_info = client.lookup(
    'ENSG00000139618',  # BRCA2 Ensembl ID
    expand=True
)

直接 REST API を使用する場合（パッケージ不要）：

import requests

server = "https://rest.ensembl.org"

# Symbol lookup
response = requests.get(
    f"{server}/lookup/symbol/homo_sapiens/BRCA2",
    headers={"Content-Type": "application/json"}
)
gene_data = response.json()

2. 配列の取得

ゲノム、転写産物、またはタンパク質の配列を、さまざまな形式（JSON、FASTA、プレーンテキスト）で取得します。

操作：

• 遺伝子またはゲノム領域の DNA 配列を取得する
• 転写産物配列（cDNA）を取得する
• タンパク質配列にアクセスする
• フランキング領域や修飾を含む配列を抽出する

例：

# Using ensembl_rest package
sequence = client.sequence_id(
    id='ENSG00000139618',  # Gene ID
    content_type='application/json'
)

# Get sequence for a genomic region
region_seq = client.sequence_region(
    species='human',
    region='7:140424943-140624564'  # chromosome:start-end
)

3. バリアント解析

遺伝的バリエーションデータを照会し、Variant Effect Predictor（VEP）を使用してバリアントの影響を予測します。

機能：

• rsID またはゲノム座標でバリアントを検索する
• バリアントの機能的影響を予測する
• 集団頻度データにアクセスする
• 表現型との関連情報を取得する

VEP の例：

# Predict variant consequences (GET variant is vep_hgvs_get; POST batch is vep_hgvs_post)
vep_result = client.vep_hgvs_get(
    species='human',
    hgvs_notation='ENST00000380152.7:c.803C>T'
)

# Query variant by rsID
variant = client.variation_id(
    species='human',
    id='rs699'
)

4. 比較ゲノム解析

種をまたいだ比較を行い、オーソログ、パラログ、進化的関係を特定します。

操作：

• オーソログを探す（異なる種に存在する同じ遺伝子）
• パラログを特定する（同じ種内の関連遺伝子）
• 進化的関係を示す遺伝子ツリーにアクセスする
• 遺伝子ファミリーの情報を取得する

例：

import requests

# Find orthologs for a human gene. The species segment is required:
# GET /homology/id/:species/:id (the old /homology/id/:id path now returns 404,
# and so does ensembl_rest's homology_ensemblgene(), which still calls it).
orthologs = requests.get(
    "https://rest.ensembl.org/homology/id/human/ENSG00000139618",  # Human BRCA2
    params={"target_species": "mouse", "type": "orthologues", "format": "condensed"},
    headers={"Content-Type": "application/json"},
    timeout=60,
).json()
# -> data[0]["homologies"][0]["id"] == "ENSMUSG00000041147" (ortholog_one2one)

# Get gene tree (GET /genetree/member/symbol/:species/:symbol; large and slow)
gene_tree = client.genetree_member_symbol(
    species='human',
    symbol='BRCA2'
)

5. ゲノム領域の解析

特定の領域にあるすべてのゲノム要素（遺伝子、転写産物、制御エレメント）を検索します。

ユースケース：

• 染色体領域内のすべての遺伝子を特定する
• 制御エレメント（プロモーター、エンハンサー）を探す
• 領域内のバリアントを特定する
• 構造的特徴を取得する

例：

# Find all features in a region
features = client.overlap_region(
    species='human',
    region='7:140424943-140624564',
    feature='gene'
)

6. アセンブリマッピング

異なるゲノムアセンブリ間で座標を変換します（例：GRCh37 から GRCh38）。

重要： GRCh37/hg19 のクエリには https://grch37.rest.ensembl.org を、現行のアセンブリには https://rest.ensembl.org を使用してください。

例：

from ensembl_rest import AssemblyMapper

# Map coordinates from GRCh37 to GRCh38.
# AssemblyMapper prefetches the whole-assembly mapping on init (slow once,
# then fast for repeated point lookups). map() takes a single position.
mapper = AssemblyMapper(
    from_assembly='GRCh37',
    to_assembly='GRCh38',
    species='human'
)

mapped_pos = mapper.map(chrom='7', pos=140453136)
# For one-off lookups, the direct REST endpoint is simpler:
#   GET /map/human/GRCh37/7:140453136..140453136/GRCh38

API のベストプラクティス

レート制限

Ensembl REST API にはレート制限があります。次のプラクティスに従ってください。

1. レート制限を守る： 匿名ユーザーの場合、1 秒あたり最大 15 リクエストです
2. 429 レスポンスに対応する： レート制限に達した場合は、Retry-After ヘッダーを確認して待機します
3. バッチエンドポイントを使用する： 複数の項目をクエリする場合は、利用可能なバッチエンドポイントを使用します
4. 結果をキャッシュする： 頻繁にアクセスするデータを保存し、API 呼び出しを減らします

エラー処理

必ず適切なエラー処理を実装してください。

import requests
import time

def query_ensembl(endpoint, params=None, max_retries=3):
    server = "https://rest.ensembl.org"
    headers = {"Content-Type": "application/json"}

    for attempt in range(max_retries):
        response = requests.get(
            f"{server}{endpoint}",
            headers=headers,
            params=params
        )

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            # Rate limited - wait and retry
            retry_after = int(response.headers.get('Retry-After', 1))
            time.sleep(retry_after)
        else:
            response.raise_for_status()

    raise Exception(f"Failed after {max_retries} attempts")

インストール

Python パッケージ（任意の利便機能）

uv pip install 'ensembl_rest==0.3.4'   # latest release: Oct 2023

ensembl_rest パッケージ（Ad115/EnsemblRest）は REST エンドポイントをラップしますが、機能が限定的で、2023 年以降メンテナンスされていません。同梱の scripts/ensembl_query.py は代わりに標準の requests を使用しており、このパッケージにはないレート制限と再試行処理を追加しているため、こちらの使用を推奨します。

メソッド名に関する注意点： このパッケージは、エンドポイントのドキュメント URL の 最後のセグメント から各メソッド名を自動生成します。これは REST パスとは逆になることが多く、混乱を招きます。

REST エンドポイント	EnsemblClient のメソッド
GET /lookup/symbol/...	symbol_lookup
GET /lookup/id/...	lookup（lookup_id ではありません）
GET /info/assembly/...	assembly_info（info_assembly ではありません）
GET /info/species	species
GET /vep/:species/hgvs/...	vep_hgvs_get（POST バッチ：vep_hgvs_post）
GET /sequence/id/...	sequence_id
GET /homology/id/:species/:id	動作するものはありません。homology_ensemblgene は廃止された /homology/id/:id を呼び出すため（404）、requests または homology_symbol を使用してください

不明な場合は、パスが明確な直接 REST 呼び出しを優先してください。

REST API を直接使用する

インストールは不要です。requests などの標準 HTTP ライブラリを使用します。

uv pip install requests

リソース

references/

• api_endpoints.md：17 種類すべての API エンドポイントカテゴリについて、例とパラメーターを含む包括的なドキュメント

scripts/

• ensembl_query.py：レート制限とエラー処理を組み込んだ、一般的な Ensembl クエリ用の再利用可能な Python スクリプト

一般的なワークフロー

ワークフロー 1：遺伝子アノテーションパイプライン

1. シンボルで遺伝子を検索し、Ensembl ID を取得します
2. 転写産物の情報を取得します
3. すべての転写産物のタンパク質配列を取得します
4. 他の種のオルソログを見つけます
5. 結果をエクスポートします

ワークフロー 2：バリアント解析

1. rsID または座標でバリアントをクエリします
2. VEP を使用して機能的影響を予測します
3. 集団頻度を確認します
4. 表現型との関連を取得します
5. レポートを生成します

ワークフロー 3：比較解析

1. 参照種で対象の遺伝子を指定します
2. 対象種のオルソログを見つけます
3. すべてのオルソログの配列を取得します
4. 遺伝子構造と特徴を比較します
5. 進化的保存性を解析します

種とアセンブリの情報

利用可能な種とアセンブリをクエリするには、次のようにします。

# List all available species (method is species, for GET /info/species)
species_list = client.species()

# Get assembly information for a species (method is assembly_info, for GET /info/assembly/:species)
assembly_info = client.assembly_info(species='human')

一般的な種識別子：

• ヒト：homo_sapiens または human
• マウス：mus_musculus または mouse
• ゼブラフィッシュ：danio_rerio または zebrafish
• ショウジョウバエ：drosophila_melanogaster

追加リソース

• 公式ドキュメント： https://rest.ensembl.org/documentation
• Python パッケージのドキュメント： https://ensemblrest.readthedocs.io
• EBI トレーニング： https://www.ebi.ac.uk/training/online/courses/ensembl-rest-api/
• Ensembl（新しいプラットフォーム）： https://www.ensembl.org — GraphQL ヘルプ： https://www.ensembl.org/help/articles/getting-started-with-ensembl-graph-ql-services
• リリース 116 アーカイブ（従来のブラウザー）： https://jun2026.archive.ensembl.org
• GitHub の例： https://github.com/Ensembl/ensembl-rest/wiki