interpro-database

InterPro 数据库访问

前提条件

1. uv：阅读 uv 技能，并按照其中的设置说明，确保已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/interpro_database_LICENSE.txt，则 (1) 显著提醒用户查看 https://www.ebi.ac.uk/interpro/ 和 https://www.ebi.ac.uk/about/terms-of-use/ 上的条款，然后 (2) 创建该文件，记录通知文本和时间戳。

概述

InterPro 将多个不同数据库中的特征整合到一个可搜索的资源中，从而减少冗余，并帮助用户解读序列分析结果。通过整合这些成员数据库（例如 Pfam、CDD、SMART），InterPro 汇集各数据库的优势，打造出强大的诊断工具和集成资源。

使用 interpro-database 来：

• 确定特定蛋白质中存在哪些结构域、家族和位点。
• 找出属于某个蛋白质家族或包含特定结构域的所有蛋白质，即使这些蛋白质的名称和功能差异很大。
• 查看存在特定蛋白质家族或结构域的物种。
• 使用蛋白质家族信息和基因本体（GO）术语注释基因组。

此技能提供了一个可靠的实用工具 interpro_client.py，可与 InterPro API 无缝交互。它原生处理速率限制（HTTP 429）、后台查询等待跟踪（HTTP 408）、终止错误（HTTP 404/410）和惰性分页。

核心规则

• 使用封装脚本：查询数据库时，务必执行 scripts/interpro_client.py 辅助脚本，而不是直接访问数据库。该脚本会自动强制执行公平使用规则并实现重试逻辑。
• 对于探索性查询：务必使用 CLI 并严格设置 --limit。这样可以快速了解数据架构，避免污染上下文窗口或获取数百万条结果。
• 输出到文件：使用 CLI 的 --output 将结果输出到文件，而不要尝试将所有内容打印到控制台。使用 jq 或代码处理输出。
• 对于更复杂的工作流，请在 Python 脚本中原生导入该模块，直接使用生成器，避免在大型工作流中反序列化 CLI 字符串。
• 通知：如果使用了此技能，请确保在输出中提及。

示例：

uv run ./scripts/interpro_client.py fetch protein --source_db reviewed --limit 2 --query_params tax_id=9606 --output exploratory_results.jsonl

import sys
sys.path.append('scripts')
from interpro_client import fetch_interpro_data
import itertools

# fetch_interpro_data lazily yields results page-by-page
results = fetch_interpro_data(
    endpoint="entry",
    source_db="pfam",
    query_params={"page_size": 10}
)
for match in itertools.islice(results, 10):
    print(match["metadata"]["accession"])

构造端点的 4 种方式：

参数严格对应 4 种常见的 API 路径构造方式。不要自行构造以 / 分隔的字符串：

1. /{endpoint}（例如 /entry）uv run ./scripts/interpro_client.py fetch entry --limit 10 --output entries.jsonl
2. /{endpoint}/{sourceDB}（例如 /entry/pfam）uv run ./scripts/interpro_client.py fetch entry --source_db pfam --limit 10 --output pfam_entries.jsonl
3. /{endpoint}/{sourceDB}/{accession}（例如 /entry/pfam/PF00001）uv run ./scripts/interpro_client.py fetch entry --source_db pfam --accession PF00001 --limit 10 --output pf00001_entry.jsonl
4. /{endpoint}/{sourceDB}/{linked_endpoint}/{sourceDB}/{accession}（例如 /entry/interpro/protein/uniprot/P04637）uv run ./scripts/interpro_client.py fetch entry \ --source_db interpro \ --linked_endpoint protein \ --linked_source_db uniprot \ --linked_accession P04637 \ --limit 10 --output p04637_entries.jsonl

有效的源数据库（--source_db）

每个端点只接受特定的 source_db 值。使用无效值会返回 404 错误。

• /entry（16 个值）：interpro、pfam、cathgene3d、ssf、 panther、cdd、profile、smart、ncbifam、prosite、prints、 hamap、pirsf、sfld、antifam。
• /protein（3 个值）：uniprot（全部）、reviewed（SwissProt）、 unreviewed（TrEMBL）。
• /structure（1 个值）：pdb。
• /taxonomy（1 个值）：uniprot。
• /proteome（1 个值）：uniprot。
• /set（2 个值）：pfam、cdd。

快速参考 / 核心端点和参数

完整、详尽的所有查询参数列表，请参阅 完整 API 参考。

该 API 完全开放，支持 6 个核心端点。你可以使用上文介绍的关联参数将它们组合起来。以下按层级列出了各个端点可用的具体查询参数：

• /entry（域、家族、活性位点、重复或同源超家族条目）

  • integrated：按整合状态筛选（例如 pfam）。
  • type：按类型筛选（例如 family、domain、 homologous_superfamily）。
  • go_term / go_category：按 Gene Ontology 筛选。
  • ida_search / ida_ignore / exact / ordered：按域架构筛选 （参见 IDA 搜索部分）。
  • extra_fields：请求其他数据（例如用于匹配坐标的 counters）。
  • group_by / sort_by：聚合或排序结果 (有效值取决于上下文，参见 完整 API 参考)。
  • 示例：uv run ./scripts/interpro_client.py count entry --source_db pfam --query_params type=domain --output count.jsonl

• /protein（匹配条目或域的蛋白质记录）

  • tax_id：按分类 ID 筛选（不搜索谱系）。
  • match_presence：按是否具有 InterPro 匹配项的蛋白质筛选 （true/false）。
  • is_fragment：筛选完整序列或片段序列。
  • group_by：聚合结果（例如 taxonomy）。
  • extra_fields：请求序列或匹配项详情。
  • isoforms / residues / structureinfo：包含特定子特征。
  • conservation / extra_features：附加残基保守性标记或 Mobidb/coil 特征 (仅适用于 /protein/{source_db}/{accession})。
  • 示例：uv run ./scripts/interpro_client.py fetch protein --source_db uniprot --limit 20 --query_params tax_id=9606 --output human_proteins.jsonl

• /structure（与 InterPro 条目关联的 PDB 结构）

  • experiment_type：按实验方法筛选（例如 X-RAY DIFFRACTION）。
  • resolution：按分辨率限制筛选。
  • extra_fields：包含其他结构元数据。
  • group_by：聚合结果。
  • 示例：./scripts/interpro_client.py fetch structure --source_db pdb --accession 1ATP --limit 10 --output 1atp_structures.jsonl

• /taxonomy（分类分布节点）

  • key_species：筛选并限制为关键物种。
  • with_names：包含学名。
  • filter_by_entry / filter_by_entry_db：筛选与指定条目的交集。
  • extra_fields：其他分类学元数据。
  • 示例：./scripts/interpro_client.py fetch taxonomy --source_db uniprot --accession 9606 --limit 10 --output human_taxonomy.jsonl

• /proteome（与 InterPro 关联的完整蛋白质组）

  • extra_fields：通用查询扩展。
  • 示例：uv run ./scripts/interpro_client.py fetch proteome --source_db uniprot --accession UP000005640 --limit 10 --output proteome.jsonl

• /set（相关条目的整理集合，例如 Pfam 簇）

  • extra_fields：其他元数据 (仅适用于 /set/{sourceDB})。
  • 示例：uv run ./scripts/interpro_client.py fetch set --source_db pfam --accession CL0001 --limit 10 --output pfam_clan.jsonl

InterPro 域架构（IDA）搜索

InterPro 提供了强大的工具，可按域架构（域的确切组合及顺序）搜索蛋白质。由于 API 不支持直接按多个域查询蛋白质（例如，“查找同时包含 PF00069 和 PF00017 的蛋白质”），因此查找具有特定域组合的蛋白质需要分两步进行。

步骤 1：查找匹配的架构（ida_search）

ida_search 参数用于根 /entry 端点，可查找包含你指定结构域的所有领域架构（IDA）。

• 限制：
  • 仅在根 /entry 端点上有效。
  • 不能与非 IDA 参数组合使用。
• 修饰符（仅与 ida_search 配合使用）：
  • ida_ignore：在搜索中忽略给定的结构域（查询参数）。
  • ordered：确保结构域严格按照指定顺序出现（标志）。
  • exact：确保架构完全匹配（不包含其他结构域）（标志）。必须同时提供 ordered 标志。

示例：查找同时包含激酶结构域（PF00069）和 SH2 结构域（PF00017），且顺序完全一致的架构：

uv run scripts/interpro_client.py fetch entry
  --query_params ida_search=PF00069,PF00017
  --flags ordered exact
  --output architectures.jsonl

注意：此操作返回架构及其唯一的 ida_id，而非所有单个蛋白质。

步骤 2：获取这些架构对应的蛋白质（ida）

获得步骤 1 中的 ida_id（例如 619edbb...）后，可以通过筛选 /protein 端点，获取共享该精确布局的所有实际蛋白质。

限制：

• 适用于 /protein 和 /entry/{sourceDB}/{accession} 端点。

示例：获取与步骤 1 中某个架构 ID 匹配的蛋白质：

uv run scripts/interpro_client.py fetch protein
  --source_db uniprot
  --query_params ida=619edbb2b445bfa3ad51bd894e3c115b025a5f25
  --output matching_proteins.jsonl

（构建流水线或进行全面查询时，可遍历步骤 1 中的所有 ida_id，并针对每个 ID 执行步骤 2。）

InterPro 条目类型

每个 InterPro 条目都会被分配一种类型，用以说明蛋白质匹配该条目时可以推断出什么：

• 结构域：具有明确功能、结构或序列特征的单元，可存在于各种生物学环境中。例如：PH 结构域或经典 C2H2 锌指。
• 家族：一组具有共同进化起源的蛋白质，其共同起源体现在相关功能、序列相似性或一级、二级、三级结构上。
• 同源超家族：具有共同进化起源的蛋白质，其共同起源体现在结构相似性上，但序列相似性通常很低。通常包含来自 SUPERFAMILY 和 CATH-Gene3D 数据库的特征。
• 重复序列：通常在蛋白质中重复出现的短序列，长度往往小于 50 个氨基酸。例如：富含亮氨酸重复序列或 WD40 重复序列。
• 位点：包括 Active site（包含催化活性所需保守残基的序列）和 Binding site（包含形成蛋白质相互作用位点所需保守残基的序列）。

InterPro-N 预测

InterPro-N 是标准 InterPro 数据库的深度学习扩展。它采用受计算机视觉启发的 AI 架构，将蛋白质序列注释视为“全景分割”任务，对残基进行标注并区分结构域。

何时使用 InterPro-N

标准 InterPro 特征是“金标准”，不应为了 InterPro-N 预测而弃用。应主要使用 InterPro-N 来填补空缺或完善结果。

除标准 InterPro 外：

• 分析“暗物质”（未表征蛋白质）：当蛋白质在标准 InterPro 中没有任何匹配结果时使用。InterPro-N 擅长识别远缘同源物。
• 解析复杂重复序列：用于包含多个串联重复序列（例如 TPR 或 WD40）的蛋白质，因为标准 HMM 可能会将它们合并或漏掉。
• 预测不连续结构域：当结构域序列被完全不同的插入序列打断时使用。

替代标准 InterPro（特定场景）：

• 精确界定边界：当你需要比标准模糊匹配更准确的结构域起止坐标时使用。
• 大规模宏基因组筛查：用于对片段化或高度分化的序列进行初步筛查，以尽可能提高检出率。

回退策略：检查 InterPro-N

当你被要求查找某种蛋白质的注释，而标准 InterPro 查询没有返回结果或注释时，你必须将 InterPro-N 作为回退方案进行检查。

**示例场景：**如果用户要求“列出蛋白质 X 的 SSF 注释”，而标准查询没有返回任何匹配项，你应该使用 interpro_n 标志重试查询。

这个回退方案至关重要，因为 InterPro-N 可以识别标准方法无法发现的“暗物质”蛋白质中的远缘同源物和结构域。

如果找到注释，务必告知用户这些是来自 InterPro-N 的深度学习预测结果。

使用方法

将 interpro_n 标志传递给 protein 端点，并将 uniprot 设为源数据库，即可获取 InterPro-N 预测结果。

通过 CLI：

uv run ./scripts/interpro_client.py fetch protein
    --source_db uniprot
    --accession A0A096LNN2
    --flags interpro_n
    --output A0A096LNN2_interpro_n.jsonl

通过 Python Pipeline：

results = fetch_interpro_data(
    endpoint="protein",
    source_db="uniprot",
    accession="A0A096LNN2",
    flags=["interpro_n"])

严格查询规则

1. **始终使用 UniProt 登录号，绝不使用基因名称：**在 InterPro 中查询蛋白质时，你必须使用其 UniProt 登录号（例如 P04637）。InterPro 原生不支持基因名称（例如 TP53），也无法可靠地将其映射。如果用户提供的是基因名称，你必须先使用 Ensembl 或 UniProt 等数据库将其解析为登录号。

2. **绝不通过遍历计数：**当用户询问汇总数量（例如“有多少个结构域？”）时，你必须使用 get_interpro_count() 辅助函数，从初始 API JSON 响应中读取 count 字段。绝不遍历 fetch_interpro_data 生成器来统计元素数量。仅为计数就遍历包含 50,000 多个条目的端点，会导致 Agent 无声挂起并滥用 API。每次都是如此，没有例外。

   ✅ 正确：

   通过 CLI：

   uv run ./scripts/interpro_client.py count entry
       --source_db interpro
       --query_params type=domain
       --output count.json
   

   通过 Python Pipeline：

   from interpro_client import get_interpro_count
   cnt = get_interpro_count(
       endpoint="entry",
       source_db="interpro",
       query_params={"type": "domain"},
   )
   

   ❌ 错误（遍历 fetch）：

   # 绝不要这样做：
   uv run ./scripts/interpro_client.py fetch entry
       --source_db interpro
       --query_params type=domain
       --output output.jsonl
       && wc -l output.jsonl
   

快速示例

**有关各个端点调用方式及其返回的 JSON 输出架构的详细示例，请参阅 示例响应参考。**此 TSV 文件包含命令行调用、 Python 等效代码以及相应的 JSON 载荷结构。

1. 确定所有蛋白质结构域

# Fetches InterPro Entries within UniProt protein P04637
# URL equivalent: /entry/interpro/protein/uniprot/P04637
uv run ./scripts/interpro_client.py fetch entry
    --source_db interpro
    --linked_endpoint protein
    --linked_source_db uniprot
    --linked_accession P04637
    --output p04637_domains.jsonl

2. 获取某个 Entry 的所有 PDB 结构

# URL equivalent: /structure/pdb/entry/interpro/IPR011615
# Only fetch the first 5 structures
uv run ./scripts/interpro_client.py fetch structure
    --source_db pdb
    --linked_endpoint entry
    --linked_source_db interpro
    --linked_accession IPR011615
    --output ipr011615_structures.jsonl