alterlab-ensembl

Ensembl 数据库

概述

访问和查询 Ensembl 基因组数据库，这是由 EMBL-EBI 维护的综合性脊椎动物基因组数据资源。该数据库提供超过 250 个物种的基因注释、序列、变异、调控信息和比较基因组学数据。经典 REST API 提供 release 116 的数据（于 2026 年 6 月 9 日发布；GET /info/software → {"release": 116}）。

请注意（已于 2026-09-23 核实）： Release 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 人类数据最简单的途径；对于 release 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. **遵守速率限制：**匿名用户每秒最多发起 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 API——其路径明确无歧义。

直接调用 REST API

无需安装——使用 requests 等标准 HTTP 库：

uv pip install requests

资源

references/

• api_endpoints.md：全面介绍所有 17 类 API 端点，并提供示例和参数

scripts/

• ensembl_query.py：可复用的 Python 脚本，用于执行常见的 Ensembl 查询，内置速率限制和错误处理

常见工作流

工作流 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
• Release 116 存档（经典浏览器）： https://jun2026.archive.ensembl.org
• GitHub 示例： https://github.com/Ensembl/ensembl-rest/wiki