uniprot-database

UniProt 数据库访问

先决条件

1. uv：阅读 uv 技能，并按照其中的设置说明，确保已安装 uv 且已将其添加到 PATH。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/uniprot_database_LICENSE.txt，则 (1) 显著提醒用户查看 https://www.uniprot.org/help/license 和 https://www.uniprot.org/help/api_queries 中的条款，然后 (2) 创建该文件，记录通知文本和时间戳。

概述

提供对 UniProt 知识库（UniProtKB）、非冗余序列档案（UniParc）和聚类序列集（UniRef）的直接程序化访问。此技能支持蛋白质发现、交叉引用、经整理的生物学数据检索和底层数据库查询。

核心规则

• 使用封装工具：始终使用提供的 Python 脚本（例如 scripts/uniprot_tools.py），而不要自行构造 curl 请求。
• 禁止编造：不得编造蛋白质功能、元数据或序列。对于可由此技能中的服务处理的任务，必须严格依据工具输出，而非依赖自身已有知识。
• 通知：如果使用了此技能，请确保在输出中提及。

使用场景

• 搜索蛋白质功能：查询功能注释、GO 术语、亚细胞定位等。
• 搜索蛋白质序列：在 UniProtKB、UniParc 和 UniRef 中，根据功能注释、基因等搜索蛋白质序列。
• 了解蛋白质与生物体之间的关系：利用分类数据库和蛋白质组集。
• 大规模元数据检索：通过流式处理获取数千种蛋白质的注释。
• 序列发现：通过 UniParc 查找直系同源物或非模式蛋白质。
• ID 映射：在 UniProt 和 100 多个外部数据库之间转换 ID。
• 历史数据（UniSave）：检索条目的先前版本或追踪已删除的序列。

可用工具

根据任务类型和数据量选择合适的工具：

• get：获取特定条目的元数据和序列。最适合单个已知登录号。
  • 也可访问 UniSave 历史数据（使用 --dataset unisave），这对于协调旧版本的数据，或查明为何以前有效的登录号不再出现在搜索结果中至关重要。
• search：搜索符合查询条件的条目。最适合探索和发现。
  • 使用 --limit 5，在开始大规模下载前确认查询是否返回预期的蛋白质。
  • 如果结果超过 500 个条目，会自动分页，以便稳定下载。
  • 警告：对于分页搜索，使用 --limit 时 TXT 等格式并不可靠，因为它限制的是行数，而非条目数。
  • 参见搜索查询字段文档。
• stream：流式传输所有匹配的条目。最适合批量检索大型数据集（最多 10,000,000 个条目）。
  • 不支持 --limit；始终返回完整结果集。
  • 如果需要子集，请使用带 --limit 的 search。
• count：统计符合查询条件的条目数。最适合回答直接的计数问题，或在执行完整的 search 或 stream 之前进行初步估算。
• sparql：执行图查询，以进行复杂的数据发现。最适合计数、精确序列匹配和多数据库查询。
  • 参见 SPARQL 示例。
• map：在 UniProt 和 100 多个数据库之间转换 ID。最适合 ID 映射任务。
  • 参见 ID 映射文档。
  • search 与 map：如果用户没有明确要求使用 map，请先尝试 search。例如，外部 ID 可能可在 UniParc 中搜索到，但无法映射到 UniProtKB。

工作流

典型的蛋白质研究工作流

复制此清单并跟踪进度：

• 步骤 1：确定目标蛋白质和生物体。
• 步骤 2：在 UniProtKB 中搜索已审核条目（reviewed:true）。
• 步骤 3：如果没有已审核条目，则搜索未经审核的条目，或使用 UniParc 查找序列。
• 步骤 4：必要时，将外部 ID（如 Ensembl、PDB）映射到 UniProt 登录号。
• 步骤 5：以所需格式（JSON、FASTA）获取功能元数据或序列。

处理搜索未命中的情况（例如，在非模式生物中搜索基因）

如果直接查询（例如 gene:SYMBOL）失败：

1. 改用蛋白质名称：搜索常见的蛋白质名称（例如，protein_name:Alpha-crystallin A）。
2. 使用 UniParc：搜索 UniParc 数据集。该数据集整合了来自所有生物的序列，即使这些序列尚未在 UniProtKB 中得到完整注释。
3. 检查直系同源物／标准序列：先确定人类／小鼠的直系同源物，以找到正确的命名／助记符。

批量检索优先级

重要

批量数据始终优先使用 stream 或 sparql。 search 适合探索；如果结果超过 500 个条目，它会自动分页，以便稳定下载。

• 优先级 0：count：运行 search 或 stream 之前，务必先检查结果数量。
• 优先级 1：stream：批量数据检索的主要方式（最多 10M 个条目）。不支持 --limit；始终返回所有结果。
• 优先级 2：sparql：最适合在检索时进行复杂筛选和精确匹配。

基于序列的搜索（精确匹配）

重要

按完整氨基酸序列搜索蛋白质时，请使用 SPARQL。REST API 的 /search 端点不支持直接按序列字符串查找。对于任何非精确匹配，请使用专用的序列相似性搜索技能。如果在 UniProt 中找不到查询结果，请使用 UniParc。

SPARQL 查询模式（UniProt）：

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
SELECT ?protein ?name WHERE {
  ?protein a up:Protein ;
           up:sequence/rdf:value "SEQUENCE_HERE" .
  OPTIONAL {
    ?protein up:recommendedName/up:fullName ?name .
  }
}

SPARQL 查询模式（UniParc）：

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

SELECT ?uniparc ?val WHERE {
  GRAPH <http://sparql.uniprot.org/uniparc> {
    ?uniparc a up:Sequence ;
             rdf:value ?val .
    FILTER (?val = "SEQUENCE_HERE")
  }
}

高效统计条目数量

重要

统计条目数量（例如“人类中有多少种蛋白质？”）时，请使用 count 或 SPARQL。

统计模式（按生物体统计蛋白质）：

PREFIX up: <http://purl.uniprot.org/core/>
PREFIX taxon: <http://purl.uniprot.org/taxonomy/>
SELECT (COUNT(?protein) AS ?count) WHERE {
  ?protein a up:Protein ;
           up:reviewed true ;
           up:organism taxon:9606 .
}

REST 搜索语法

• 列表中不要使用逗号：逗号会被视为字面内容。请使用大写的 OR 分隔项目。
  • 分组：accession:(P12345 OR P67890)
  • 重复：accession:P12345 OR accession:P67890
• 空格表示 AND：例如，gene:p53 human 会同时搜索两者。

示例命令

以下是 uniprot_tools.py 各种模式的示例命令。

统计给定查询的条目总数。

uv run scripts/uniprot_tools.py count "taxonomy_id:9606"

搜索条目。

uv run scripts/uniprot_tools.py search "gene:p53 AND reviewed:true" --limit 5

按登录号检索单个条目。

uv run scripts/uniprot_tools.py get P04637

检索历史/已删除条目（UniSave）。

uv run scripts/uniprot_tools.py get P04637 --dataset unisave

流式检索大型结果集以进行批量获取（返回所有匹配的条目，不支持 --limit）。

uv run scripts/uniprot_tools.py stream "taxonomy_id:9606 AND reviewed:true" --format tsv --fields accession,gene_names > human_reviewed.tsv

将 ID 从一个数据库映射到另一个数据库。

uv run scripts/uniprot_tools.py map "P04637" --from_db UniProtKB_AC-ID --to_db Gene_Name

使用 SPARQL 执行图查询。

uv run scripts/uniprot_tools.py sparql 'PREFIX up: <http://purl.uniprot.org/core/> SELECT ?protein WHERE { ?protein a up:Protein ; up:reviewed true . } LIMIT 5'

常见错误

• 使用 name: 而非 protein_name:：name: 不是受支持的查询词，请改用 protein_name:。
• 忽略 UniParc：非模式生物可能只存在于 UniParc 中。
• 混淆 Accession 和 UPI：UniProtKB 登录号（例如 P04637）关联功能元数据；UniParc ID（UPI...）仅用于序列。你可以使用 ID Mapping 工具查找 UniParc ID 到 UniProtKB 登录号的交叉引用。
• 在 ID Mapping 中将 UniProtKB-AC 用作目标：请改用 UniProtKB。
• 放弃复杂查询：如果复杂搜索查询失败，请尝试使用 SPARQL，而不是直接放弃。
• 使用 ID 却不核实其含义：切勿假设自己知道某个 ID 的含义（例如，关键词、GO 术语、Pfam ID 等）。在将 ID 用于搜索前，务必先在 UniProt 中查找其自然语言描述或含义，确保它符合你预期的搜索词。
• 忽略宽泛搜索中的引用噪声：宽泛的文本搜索（search "term"）经常会返回误报（例如，常见的管家蛋白），因为 UniProt 会搜索完整元数据，包括出版物标题。进行功能发现时，务必优先使用字段专属筛选条件，如 cc_function: 或 protein_name:。
• 忘记给简短搜索词加引号：不加引号的简短词语（例如 lanM）可能会匹配生物名称（例如 Lancefieldella）或其他字段中的子字符串。使用引号和字段前缀（例如 gene:lanM）来筛选出真正的匹配项。
• 直接操作蛋白质序列：始终使用代码和工具执行基于序列的操作。不要尝试手动编辑、截断或修改蛋白质序列。
• 过度使用 Search 获取批量数据：如果 stream 或 sparql 可以完成任务，切勿使用 search 检索数百万条记录。对于超大型数据集，流式处理效率更高。请注意，stream 的硬性输出上限为 10,000,000 条，且不支持 --limit。
• 忘记检查数据量：在运行不带 --limit 的 search 或使用 stream 前，务必先执行 count。如果返回数百万条记录，无限制查询可能耗时很长并消耗大量资源。
• 在 stream 中使用 --limit：stream 命令不支持 --limit。如果需要限制结果数量，请改用带 --limit 的 search。
• 忘记许可声明：首次展示结果时，切勿遗漏对用户说明使用了 UniProt Database，并提醒用户查看许可条款。即使任务内容简短，也必须在首次包含 UniProt 数据的回复中注明此信息。

参考资料

• SPARQL 示例
• 搜索查询字段文档
• ID Mapping 文档
• UniProt 证据文档
• 底层 API 端点（由 scripts/uniprot_tools.py 使用）：
  • get、search、stream、count -> rest.uniprot.org/{dataset}/
  • map -> rest.uniprot.org/idmapping/
  • sparql -> sparql.uniprot.org/sparql
  • get --dataset unisave -> rest.uniprot.org/unisave/