alterlab-uniprot

UniProt 数据库

概述

UniProt 是全球领先的综合性蛋白质序列与功能信息资源。可按名称、基因或登录号搜索蛋白质，以 FASTA 格式获取序列，在不同数据库之间进行 ID 映射，并通过 REST API 访问 Swiss-Prot/TrEMBL 注释，用于蛋白质分析。

何时使用此技能

在以下情况下应使用此技能：

• 按名称、基因符号、登录号或生物体搜索蛋白质条目
• 以 FASTA 或其他格式获取蛋白质序列
• 在 UniProt 与外部数据库（Ensembl、RefSeq、PDB 等）之间映射标识符
• 访问蛋白质注释，包括 GO 术语、结构域和功能描述
• 高效批量获取多个蛋白质条目
• 查询已审阅（Swiss-Prot）或未审阅（TrEMBL）的蛋白质数据
• 流式获取大型蛋白质数据集
• 使用特定字段的搜索语法构建自定义查询

不适用的情况

场景	改用
实验确定的 3D 结构和坐标	alterlab-pdb
AI 预测的结构和 pLDDT 置信度	alterlab-alphafold-db
蛋白质相互作用网络	alterlab-string-db
结构域架构和家族分类	alterlab-interpro
序列相似性搜索（BLAST）	alterlab-blast

核心能力

1. 搜索蛋白质

使用自然语言查询或结构化搜索语法搜索 UniProt。

常见搜索模式：

# Search by protein name
query = "insulin AND organism_name:\"Homo sapiens\""

# Search by gene name
query = "gene:BRCA1 AND reviewed:true"

# Search by accession
query = "accession:P12345"

# Search by sequence length
query = "length:[100 TO 500]"

# Search by taxonomy
query = "taxonomy_id:9606"  # Human proteins

# Search by GO term
query = "go:0005515"  # Protein binding

使用 API 搜索端点：https://rest.uniprot.org/uniprotkb/search?query={query}&format={format}

支持的格式： JSON、TSV、Excel、XML、FASTA、RDF、TXT

2. 获取单个蛋白质条目

按登录号获取特定蛋白质条目。

登录号格式：

• 经典格式：P12345、Q1AAA9、O15530（6 个字符：字母 + 5 个字母数字字符）
• 扩展格式：A0A022YWF9（较新条目使用 10 个字符）

获取端点： https://rest.uniprot.org/uniprotkb/{accession}.{format}

示例：https://rest.uniprot.org/uniprotkb/P12345.fasta

3. 批量获取和 ID 映射

在不同数据库系统之间映射蛋白质标识符，并高效获取多个条目。

ID 映射工作流：

1. 提交映射任务（POST）：https://rest.uniprot.org/idmapping/run，参数为 from、to、ids
2. 轮询任务状态：https://rest.uniprot.org/idmapping/status/{jobId}
3. 获取结果：https://rest.uniprot.org/idmapping/results/{jobId}

两个不太明显的注意事项（均已在 scripts/uniprot_client.py 中处理）：

• 状态端点会先返回 {"jobStatus":"RUNNING"}，然后返回 {"jobStatus":"FINISHED"}（任务完成后也会通过 303 重定向至结果 URL）。它不会返回 results/failedIds 键，因此应在 jobStatus == "FINISHED" 时轮询，而不是检查是否存在 results。
• 结果采用分页形式（默认 size=25，最大 500）。对于大型映射，第一页只包含部分结果；请持续跟随 next Link 响应标头（在 requests 中为 response.links["next"]），直到该链接消失。相同的 next Link 分页方式也适用于 /uniprotkb/search 端点——JSON 正文只包含 results，不会包含 next 键。

支持映射的数据库：

• UniProtKB AC/ID
• 基因名称
• Ensembl、RefSeq、EMBL
• PDB、AlphaFoldDB
• KEGG、GO 术语
• 以及更多数据库（参见 /references/id_mapping_databases.md）

限制：

• 每个任务最多支持 100,000 个 ID
• 结果保存 7 天

4. 流式获取大型结果集

对于超出分页限制的大型查询，请使用 stream 端点：

https://rest.uniprot.org/uniprotkb/stream?query={query}&format={format}

stream 端点会返回所有结果，不进行分页，适合下载完整数据集。

5. 自定义检索字段

准确指定要检索的字段，以实现高效的数据传输。

常用字段：

• accession - UniProt 登录号
• id - 条目名称
• gene_names - 基因名称
• organism_name - 生物体
• protein_name - 蛋白质名称
• sequence - 氨基酸序列
• length - 序列长度
• go_* - 基因本体注释
• cc_* - 注释字段（功能、相互作用等）
• ft_* - 特征注释（结构域、位点等）

示例： https://rest.uniprot.org/uniprotkb/search?query=insulin&fields=accession,gene_names,organism_name,length,sequence&format=tsv

完整字段列表请参见 /references/api_fields.md。

Python 实现

如需以编程方式访问，请使用提供的辅助脚本 scripts/uniprot_client.py，其中实现了：

• search_proteins(query, format) - 使用任意查询搜索 UniProt
• get_protein(accession, format) - 检索单个蛋白质条目
• map_ids(ids, from_db, to_db) - 在不同标识符类型之间进行映射
• batch_retrieve(accessions, format) - 检索多个条目
• stream_results(query, format) - 流式获取大型结果集

可选 Python 软件包：

• Unipressed：现代化、带类型的 UniProt REST API 客户端
• bioservices：功能全面的生物信息学 Web 服务客户端

查询语法示例

布尔运算符：

kinase AND organism_name:human
(diabetes OR insulin) AND reviewed:true
cancer NOT lung

字段专用搜索：

gene:BRCA1
accession:P12345
organism_id:9606
taxonomy_name:"Homo sapiens"
ft_signal:*

当前 API 对 2022 年以前的 annotation:(type:...)、database:(type:...)、created:/modified: 和 existence:"Evidence at protein level" 形式的查询会返回 HTTP 400；请改用 ft_<feature>:*、database:<db>、date_created:/date_modified: 和 existence:1。

范围查询：

length:[100 TO 500]
mass:[50000 TO 100000]

通配符：

gene:BRCA*
protein_name:kinase*

全面的语法文档请参见 /references/query_syntax.md。

最佳实践

1. 尽可能使用经审核的条目：使用 reviewed:true 筛选 Swiss-Prot（人工整理）条目
2. 明确指定格式：选择最合适的格式（序列使用 FASTA，表格数据使用 TSV，程序化解析使用 JSON）
3. 使用字段选择：只请求所需字段，以减少带宽占用和处理时间
4. 处理分页：对于大型结果集，请实现适当的分页，或使用流式端点
5. 缓存结果：将经常访问的数据存储在本地，以尽量减少 API 调用
6. 限制请求速率：请合理使用 API 资源；进行大型批量操作时应加入延迟
7. 检查数据质量：TrEMBL 条目是计算预测结果；Swiss-Prot 条目经过人工审核

资源

scripts/

uniprot_client.py - Python 客户端，提供常见 UniProt 操作的辅助函数，包括搜索、检索、ID 映射和流式获取。

references/

• api_fields.md - 可用于自定义查询的完整字段列表
• id_mapping_databases.md - ID 映射操作支持的数据库
• query_syntax.md - 全面的查询语法及高级示例
• api_examples.md - 多种语言的代码示例（Python、curl、R）

其他资源

• 当前使用的版本：每个响应都包含 X-UniProt-Release / X-UniProt-Release-Date 响应头（审核时为 2026_03，2026 年 9 月 2 日）——请记录这些信息以确保结果可复现
• API 文档：https://www.uniprot.org/help/api
• 交互式 API 浏览器：https://www.uniprot.org/api-documentation
• REST 教程：https://www.uniprot.org/help/uniprot_rest_tutorial
• 查询语法帮助：https://www.uniprot.org/help/query-fields
• SPARQL 端点：https://sparql.uniprot.org/（用于高级图查询）