alterlab-gene-db

基因数据库

概述

NCBI Gene 是一个综合数据库，整合了多种物种的基因信息。它提供命名信息、参考序列（RefSeq）、染色体图谱、生物通路、遗传变异、表型以及与全球基因组资源的交叉引用。

何时使用此技能

处理基因数据时应使用此技能，包括按基因符号或 ID 搜索、获取基因序列和元数据、分析基因功能和通路，或批量查询基因。

不适用的情况

场景	改用
Ensembl ID、VEP 后果、直系同源基因，或 GRCh37↔GRCh38 映射	alterlab-ensembl
蛋白质层面的功能、结构域、PTM，或 UniProt ID 映射	alterlab-uniprot
变异的临床意义	alterlab-clinvar
基因列表的通路归属／富集分析	alterlab-reactome
通过 CLI 跨数据库快速进行单次基因查询	alterlab-gget

快速开始

NCBI 提供两种主要的基因数据访问 API：

1. E-utilities（传统）：功能全面的 API，支持所有 Entrez 数据库和灵活查询
2. NCBI Datasets API（较新）：针对基因数据检索进行优化，工作流更简化

复杂查询和跨数据库搜索请选择 E-utilities。直接获取基因元数据请选择 Datasets API（每次请求返回一份基因报告；转录本／蛋白质 RefSeq 登录号需通过单独的 product_report 端点获取）。

常见工作流

按符号或名称搜索基因

要跨生物体按符号或名称搜索基因：

1. 使用 scripts/query_gene.py 脚本调用 E-utilities ESearch
2. 指定基因符号和生物体（例如，“人类中的 BRCA1”）
3. 脚本会返回匹配的 Gene ID

示例查询模式（已根据 einfo.fcgi?db=gene 检查标签；诸如 [disease]、[phenotype] 或 [pathway] 这样的未知标签会被静默改写为 [All Fields] — 务必查看 ESearch 响应中的 querytranslation）：

• 基因符号：INS[sym] AND human[organism]（[gene]／[sym] 会匹配符号，因此 insulin[gene name] 不会找到结果——名称应使用 insulin[Gene Full Name]）
• 具有疾病关联的基因：dystrophin[Gene Full Name] AND "muscular dystrophy"[Disease/Phenotype]
• 细胞遗传学位置：human[organism] AND 17q21[Default Map Location] （[chromosome] 仅包含染色体编号，例如 17[chromosome]）

按 ID 获取基因信息

要获取已知 Gene ID 的详细信息：

1. 使用 scripts/fetch_gene_data.py 通过 Datasets API 获取全面数据
2. 或者，使用 scripts/query_gene.py 通过 E-utilities EFetch 获取特定格式的数据
3. 指定所需的输出格式（JSON、XML 或文本）

Datasets API 的基因报告会返回：

• 基因命名信息、别名和交叉引用（HGNC、Ensembl、UniProt/Swiss-Prot、OMIM）
• 基因组位置和组装版本映射（按组装版本，例如 GRCh38 和 T2T-CHM13）
• Gene Ontology（GO）注释
• 转录本和蛋白质数量

如需单个转录本／蛋白质的 RefSeq 登录号，请请求 product_report 端点（GET /gene/id/{id}/product_report）——基础基因报告包含数量，而非登录号。

批量查询基因

要同时查询多个基因：

1. 使用 scripts/batch_gene_lookup.py 进行高效批量处理
2. 提供基因符号或 ID 列表
3. 按符号查询时指定生物体
4. 脚本会自动处理速率限制（使用 API 密钥时每秒 10 个请求）

此工作流适用于：

• 验证基因列表
• 获取基因面板的元数据
• 交叉引用基因标识符
• 构建基因注释表

按生物学背景搜索

查找与特定生物学功能或表型相关的基因：

1. 使用 E-utilities 和基因本体（GO）术语或表型关键词
2. 按通路名称或疾病关联进行查询
3. 按生物体、染色体或其他属性筛选

搜索示例：

• 按 GO 术语搜索（索引了术语名称，但未索引 GO ID）："apoptotic process"[Gene Ontology] AND human[organism]
• 按疾病／表型搜索：diabetes[Disease/Phenotype] AND mouse[organism]
• 按通路搜索：Gene 没有通路字段——使用匹配的 GO 过程 （"insulin receptor signaling pathway"[Gene Ontology]）或通路数据库 （alterlab-reactome、alterlab-kegg）

API 访问模式

速率限制：

• 不使用 API 密钥：E-utilities 每秒 3 次请求，Datasets API 每秒 5 次请求
• 使用 API 密钥：两个 API 的速率均为每秒 10 次请求

身份验证： 在 https://www.ncbi.nlm.nih.gov/account/ 注册免费的 NCBI API 密钥，以提高速率限制。

错误处理： 两个 API 都会返回标准 HTTP 状态码。常见错误包括：

• 400：查询格式错误或参数无效
• 429：超出速率限制
• 404：未找到 Gene ID

使用指数退避策略重试失败的请求。

脚本用法

query_gene.py

使用 E-utilities（ESearch、ESummary、EFetch）查询 NCBI Gene。

python scripts/query_gene.py --search "BRCA1" --organism "human"
python scripts/query_gene.py --id 672 --format json
python scripts/query_gene.py --search "INS[sym] AND diabetes[Disease/Phenotype]" --organism human

fetch_gene_data.py

使用 NCBI Datasets API 获取全面的基因数据。

python scripts/fetch_gene_data.py --gene-id 672
python scripts/fetch_gene_data.py --symbol BRCA1 --taxon human
python scripts/fetch_gene_data.py --symbol TP53 --taxon "Homo sapiens" --output json

batch_gene_lookup.py

高效处理多个基因查询。

python scripts/batch_gene_lookup.py --file gene_list.txt --organism human
python scripts/batch_gene_lookup.py --ids 672,7157,5594 --output results.json

API 参考

如需了解端点、参数、响应格式和示例等详细 API 文档，请参阅：

• references/api_reference.md - E-utilities 和 Datasets API 的完整 API 文档
• references/common_workflows.md - 更多示例和用例模式

需要了解具体的 API 端点详情、参数选项或响应结构时，请搜索这些参考资料。

数据格式

NCBI Gene 数据可通过多种格式获取：

• JSON：结构化数据，适合程序化处理
• XML：详细的分层格式，包含完整元数据
• GenBank：带注释的序列数据
• FASTA：仅包含序列数据
• Text：易于阅读的摘要

现代应用请选择 JSON；需要详细元数据的旧系统请选择 XML；序列分析工作流请选择 FASTA。

最佳实践

1. 按基因符号搜索时始终指定生物体，以避免歧义
2. 条件允许时使用 Gene ID 进行精确查询
3. 处理多个基因时批量请求，以尽量减少 API 调用
4. 在本地缓存结果，以减少重复查询
5. 在脚本中包含 API 密钥，以获得更高的速率限制
6. 妥善处理错误，使用重试逻辑应对暂时性故障
7. 批量处理前验证基因符号，以发现拼写错误

资源

此技能包含：

scripts/

• query_gene.py - 使用 E-utilities（ESearch、ESummary、EFetch）查询基因
• fetch_gene_data.py - 使用 NCBI Datasets API 获取基因数据
• batch_gene_lookup.py - 高效处理多个基因查询

references/

• api_reference.md - E-utilities 和 Datasets API 的详细 API 文档
• common_workflows.md - 常见基因查询示例和用例