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（基因）：**人类基因的稳定标识符。其他物种使用不同的三字母物种代码。
• **ENST（转录本）：**转录本（剪接异构体）的稳定标识符。
• **ENSP（蛋白质）：**翻译后蛋白质的稳定标识符。
• **MANE Select：**Ensembl 和 NCBI 共同认可的共识主转录本。
• **Canonical：**Ensembl 的代表性转录本（无 MANE 时或非人类物种使用）。

核心规则

• 使用封装脚本：务必执行提供的辅助脚本来查询数据库，而不是直接访问数据库。这些脚本会自动以适当方式执行所需的速率限制。
• **默认物种：**如果提示中未指定物种或物种不明确，则默认使用 "human"。你必须明确告知用户此默认设置，确保他们知晓。
• **主转录本：**列出基因的转录本时，除非用户明确要求列出所有可选异构体，否则仅返回 MANE Select 转录本（人类）或 Canonical 转录本（其他物种）。如果存在多个转录本且你默认选择主转录本，必须告知用户。
• **组装版本处理：**默认组装版本为 GRCh38。对于 GRCh37 请求，必须使用 --assembly GRCh37 标志。使用非默认组装版本时，必须明确告知用户。
• **输出位置：**默认情况下，脚本会将完整的 JSON/FASTA 输出写入 /tmp 中的临时文件，也可使用 --output 标志写入用户指定的文件。脚本还会将简要摘要打印到标准输出。
• 通知：如果使用了此技能，请确保在输出中提及。

可用命令

1. 解析基因 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. 规范 TSS — 获取某个基因规范转录本的转录起始 位点（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 / 规范转录本的行，并 注明完整数据位于 JSON 输出中。

解析输出

如果用户需要详细的嵌套结构数据（例如某个转录本 Exon 2 的精确整数 坐标），而标准输出中没有对此进行摘要：

1. 找到 JSON 文件（通过 --output 指定，或使用脚本打印的临时文件 路径）。
2. 使用 jq 等终端工具，或编写简短的一次性 Python 代码片段来 提取所需的特定数据点。如果 JSON 文件非常大，请勿尝试将整个文件 读入上下文。

自定义查询

如果需要进行脚本不支持的 API 调用（例如获取蛋白质结构域注释、组装版本间的坐标映射、同源性 搜索、连锁不平衡或表型查询），请阅读 references/ensembl_rest_api_reference.md，了解可用端点、参数和响应字段的完整参考。

**重要：**编写自定义脚本或使用提供脚本之外的其他方式时，必须遵守 Ensembl REST API 的速率限制（每秒最多 15 个请求），并妥善处理 429 Too Many Requests 错误（例如使用指数退避）。