Files

T

wehub-skill-sync 95742963fc chore: import zh skill ensembl-database

2026-07-13 21:35:31 +08:00

8.1 KiB

Raw Permalink Blame History

name, description

name	description
ensembl-database	查询 Ensembl 数据库以解析基因、转录本和蛋白质 ID，获取基因组或蛋白质序列，检索基因结构（外显子），以及获取变异后果与效应预测（VEP）。使用本技能作为主要的 ID 翻译器、基因组序列数据库和变异效应预测工具。

Ensembl 数据库：ID 映射与基因组特征

前置条件

uv：阅读 uv 技能并遵循其设置说明，以确保 uv 已安装并位于 PATH 中。
用户通知：如果本技能目录中尚未存在 LICENSE_NOTIFICATION.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 # 回退到同义词解析

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） — 获取基因规范转录本的转录起始位点（TSS）的单一坐标。

[!NOTE] 与标准的 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 标准输出示例：

[*] 变异：9:21971147:T>C
[*] 最严重的后果：missense_variant
[*] 发现 15 个转录本后果。

[*] VEP 预测：

  - ENST00000304494（CDKN2A）：后果 = missense_variant
  - ENST00000304494（CDKN2A）：氨基酸 = N/S
  - ENST00000304494（CDKN2A）：SIFT = 有害（0.01）
  - ENST00000304494（CDKN2A）：AlphaMissense 分类 = likely_benign
  - ENST00000304494（CDKN2A）：AlphaMissense 致病性 = 0.2129
  - ENST00000304494（CDKN2A）：保守性 = 2.05
  - ENST00000304494（CDKN2A）：剂量敏感性（单倍体不足） = 0.889228328567991
  - ENST00000304494（CDKN2A）：剂量敏感性（三倍体） = 0.135514349094646
  - ENST00000304494（CDKN2A）：功能缺失（LOEUF） = 0.791

展示 VEP 结果： 运行 VEP 命令后，你必须将标准输出中的完整 VEP 预测列表呈现给用户。该列表包含标准的 VEP 预测（后果、氨基酸、SIFT、PolyPhen）和开放许可插件结果（AlphaMissense、保守性、剂量敏感性、LOEUF、Loftee LoF、NMD、UTRAnnotator、Mutfunc）。不要只做总结——展示完整列表，以便用户看到所有预测。如果列表很长（许多转录本），则完整显示 MANE Select / canonical 转录本行，并注明完整数据在 JSON 输出中。

解析输出

如果用户需要未在标准输出中总结的详细嵌套结构数据（例如转录本外显子 2 的精确整数坐标）：

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

自定义查询

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

关键： 编写自定义脚本或使用提供脚本的替代方案时，你必须遵守 Ensembl REST API 速率限制（最大每秒 15 个请求），并优雅地处理 429 Too Many Requests 错误（例如使用指数退避）。

8.1 KiB Raw Permalink Blame History Unescape Escape