reactome-database

Reactome 数据库——生物通路查询与富集分析

概述

Reactome 是一个开源、经过整理的生物通路和反应数据库，涵盖 16 种以上物种。它提供两个 REST API：内容服务用于查询通路数据、实体和层级结构，分析服务用于基因/蛋白质列表富集分析和表达数据叠加。所有端点均返回 JSON（默认格式）或其他格式，且无需身份验证。

适用场景

• 按稳定 ID 查询通路详情（例如，R-HSA-69620 表示细胞周期）
• 按关键词搜索通路、反应或实体
• 针对 Reactome 通路运行基因列表富集分析（过度代表分析）
• 获取通路层级结构和包含关系
• 跨数据库映射标识符（UniProt、Ensembl、NCBI、ChEBI）
• 获取物种特异性通路数据（人、小鼠、大鼠及其他 13 种以上生物）
• 按令牌获取分析结果，以便分享或重新筛选
• 为多组学整合工作流构建通路背景信息
• 如需KEGG 代谢通路和跨数据库 ID 转换，请改用 kegg-database
• 如需蛋白质-蛋白质相互作用网络，请改用 string-database-ppi
• 如需带缓存功能的 Python 封装，可考虑使用 reactome2py（pip install reactome2py）

前置条件

pip install requests

API 限制：

• 无需身份验证——所有端点均公开
• 没有记录在案的硬性速率限制——批量请求之间请添加 time.sleep(0.5)，以避免造成过大负载
• 内容服务基础 URL：https://reactome.org/ContentService
• 分析服务基础 URL：https://reactome.org/AnalysisService
• 标识符输入：基因/蛋白质列表接受 UniProt ID、Ensembl 基因 ID、NCBI Gene ID、HGNC 符号、ChEBI ID、miRBase ID、KEGG ID 等

快速入门

import requests
import time

CONTENT = "https://reactome.org/ContentService"
ANALYSIS = "https://reactome.org/AnalysisService"

def reactome_get(base, path, params=None):
    """Generic Reactome REST API caller. Returns JSON or raises."""
    resp = requests.get(f"{base}{path}", params=params)
    resp.raise_for_status()
    try:
        return resp.json()
    except ValueError:
        return resp.text

# Check database version
version = reactome_get(CONTENT, "/data/database/version")
print(f"Reactome version: {version}")

# Query a pathway
pathway = reactome_get(CONTENT, "/data/query/R-HSA-69620")
print(f"Pathway: {pathway['displayName']}")
print(f"Species: {pathway['speciesName']}")
time.sleep(0.5)

# Search for pathways
results = reactome_get(CONTENT, "/search/query", params={"query": "apoptosis", "types": "Pathway"})
print(f"Found {results['found']} results for 'apoptosis'")

核心 API

1. 通路与实体查询

通过稳定 ID 获取通路、反应和生物实体的详细信息。使用快速入门中的 reactome_get 辅助函数。

# Query pathway by stable ID
pathway = reactome_get(CONTENT, "/data/query/R-HSA-69620")
print(f"Name: {pathway['displayName']}")
print(f"Stable ID: {pathway['stId']}, Species: {pathway['speciesName']}")
print(f"Schema class: {pathway['schemaClass']}")  # Pathway, TopLevelPathway, etc.
time.sleep(0.5)

# Get participating physical entities in a pathway
entities = reactome_get(CONTENT, f"/data/participants/{pathway['stId']}")
print(f"\nParticipating entities: {len(entities)}")
for e in entities[:3]:
    print(f"  {e['displayName']} ({e['schemaClass']})")
time.sleep(0.5)

# Get participating molecules with reference entities (UniProt, ChEBI, etc.)
refs = reactome_get(CONTENT, f"/data/participants/{pathway['stId']}/referenceEntities")
print(f"\nReference entities: {len(refs)}")
for r in refs[:3]:
    print(f"  {r['displayName']} — {r.get('databaseName', 'N/A')}:{r.get('identifier', 'N/A')}")

2. 搜索与发现

按关键词搜索 Reactome，并使用分面筛选。

# Keyword search filtered to Pathways
results = reactome_get(CONTENT, "/search/query", params={
    "query": "cell cycle",
    "types": "Pathway",
    "species": "Homo sapiens",
    "cluster": "true"
})
print(f"Total found: {results['found']}")
for entry in results.get("results", [])[:1]:
    for e in entry.get("entries", [])[:5]:
        print(f"  {e['stId']}: {e['name']}")
time.sleep(0.5)

# Search for proteins/complexes
proteins = reactome_get(CONTENT, "/search/query", params={
    "query": "TP53", "types": "Protein", "species": "Homo sapiens"
})
print(f"\nTP53 protein entries: {proteins['found']}")
time.sleep(0.5)

# Suggest (autocomplete)
suggestions = reactome_get(CONTENT, "/search/suggest", params={"query": "apopt"})
print(f"Suggestions: {suggestions}")

可搜索类型：Pathway、Reaction、Protein、Complex、SmallMolecule、Gene、DNA、RNA、Drug、ReferenceEntity

3. 富集分析

提交基因/蛋白质列表，针对 Reactome 通路进行过度代表分析。

import requests
import time

ANALYSIS = "https://reactome.org/AnalysisService"

# Gene list (newline-separated identifiers — UniProt, HGNC symbols, Ensembl, etc.)
gene_list = "TP53\nBRCA1\nBRCA2\nATM\nCHEK2\nCDK2\nRB1\nMDM2\nCDKN1A\nBAX"

# Submit for enrichment (POST with text body)
resp = requests.post(
    f"{ANALYSIS}/identifiers/",
    headers={"Content-Type": "text/plain"},
    data=gene_list,
    params={"pageSize": 10, "page": 1, "sortBy": "ENTITIES_FDR", "order": "ASC"}
)
resp.raise_for_status()
result = resp.json()

print(f"Analysis token: {result['summary']['token']}")
print(f"Pathways found: {result['pathwaysFound']}")
print(f"Identifiers found: {result['identifiersNotFound']}")
print(f"\nTop enriched pathways:")
for p in result["pathways"][:5]:
    print(f"  {p['stId']}: {p['name']}")
    print(f"    FDR: {p['entities']['fdr']:.2e}, "
          f"Found: {p['entities']['found']}/{p['entities']['total']}")
time.sleep(0.5)

分析接受的输入：以换行符分隔的标识符，或以制表符分隔并附带表达值的数据（用于表达数据叠加）。支持的 ID 包括 UniProt、HGNC 符号、Ensembl、NCBI Gene、ChEBI、miRBase、KEGG 等。

4. 分析结果与筛选

按令牌获取先前计算的分析结果并应用筛选条件。

import requests
import time

ANALYSIS = "https://reactome.org/AnalysisService"

# Re-fetch results by token (from a previous analysis)
token = "MjAyNTA2MTcxMDA3MzRfMQ%3D%3D"  # example — use token from Module 3

# Get results with filtering
results = requests.get(f"{ANALYSIS}/token/{token}", params={
    "pageSize": 20,
    "page": 1,
    "sortBy": "ENTITIES_FDR",
    "species": "Homo sapiens",
    "resource": "TOTAL"  # TOTAL, UNIPROT, ENSEMBL, CHEBI, etc.
})
results.raise_for_status()
data = results.json()
print(f"Token: {data['summary']['token']}")
print(f"Pathways: {data['pathwaysFound']}")
time.sleep(0.5)

# Get identifiers found in a specific pathway
pathway_detail = requests.get(
    f"{ANALYSIS}/token/{token}/found/all/{data['pathways'][0]['stId']}"
)
pathway_detail.raise_for_status()
found = pathway_detail.json()
print(f"\nIdentifiers found in {data['pathways'][0]['name']}:")
for entity in found.get("entities", [])[:5]:
    mapsTo = [m["identifier"] for m in entity.get("mapsTo", [])]
    print(f"  {entity['id']} -> {mapsTo}")

令牌持久性：分析令牌在数小时内有效。分享令牌后，协作者无需重新运行分析即可查看相同结果。可按 resource（TOTAL、UNIPROT、ENSEMBL、CHEBI 等）和 species 筛选。

5. 通路层级结构与事件

沿 Reactome 通路层级结构从顶层通路向下浏览至反应。

# Top-level pathways for human (9606 = NCBI taxonomy ID)
top = reactome_get(CONTENT, "/data/pathways/top/9606")
print(f"Top-level human pathways: {len(top)}")
for p in top[:5]:
    print(f"  {p['stId']}: {p['displayName']}")
time.sleep(0.5)

# Get contained events (sub-pathways and reactions)
events = reactome_get(CONTENT, "/data/pathway/R-HSA-69620/containedEvents")
print(f"\nContained events in Cell Cycle: {len(events)}")
for e in events[:5]:
    print(f"  {e['stId']}: {e['displayName']} ({e['schemaClass']})")
time.sleep(0.5)

# Get the full ancestor chain for a pathway
ancestors = reactome_get(CONTENT, "/data/event/R-HSA-69620/ancestors")
print(f"\nAncestors of Cell Cycle:")
for chain in ancestors:
    names = [a["displayName"] for a in chain]
    print(f"  {' > '.join(names)}")

物种标识符：使用 NCBI 分类 ID（9606=人、10090=小鼠、10116=大鼠）或物种名称。

6. 交叉引用与物种

跨数据库映射标识符并查询物种特异性数据。

# List all species in Reactome
species = reactome_get(CONTENT, "/data/species/all")
print(f"Species in Reactome: {len(species)}")
for s in species[:5]:
    print(f"  {s['displayName']} (taxId: {s['taxId']})")
time.sleep(0.5)

# Map a Reactome entity to external references
xrefs = reactome_get(CONTENT, "/data/query/R-HSA-69620/xrefs")
if isinstance(xrefs, list):
    print(f"\nCross-references for R-HSA-69620: {len(xrefs)}")
    for x in xrefs[:5]:
        print(f"  {x}")
time.sleep(0.5)

# Get orthologous pathway in another species (human → mouse)
mouse_ortho = reactome_get(CONTENT, "/data/orthology/R-HSA-69620/species/10090")
if mouse_ortho:
    for o in mouse_ortho[:3]:
        print(f"Mouse ortholog: {o['stId']}: {o['displayName']}")

关键概念

通路层级结构

Reactome 以层级结构组织知识：

层级	Schema 类	示例
顶层通路	TopLevelPathway	细胞周期、免疫系统、代谢
通路	Pathway	细胞周期检查点、有丝分裂 G1-G1/S 期
反应	Reaction	TP53 与 RB1 结合
物理实体	EntityWithAccessionedSequence	TP53 [细胞质]

通路包含子通路和反应。反应连接输入/输出物理实体。每个实体都映射到参考数据库（UniProt、ChEBI、Ensembl）。

支持的标识符

Analysis Service 接受多种标识符：

数据库	示例 ID	类型
UniProt	P04637	蛋白质
HGNC Symbol	TP53	基因符号
Ensembl Gene	ENSG00000141510	基因
NCBI Gene	7157	基因
ChEBI	CHEBI:15377	小分子
miRBase	hsa-miR-21-5p	microRNA
KEGG Gene	hsa:7157	基因（KEGG 格式）
Ensembl Protein	ENSP00000269305	蛋白质

分析令牌系统

提交分析后，Reactome 会返回一个令牌——一个用于标识结果集的 URL 安全字符串。令牌支持：

• 无需重新运行分析即可重新获取结果（GET /token/{token}）
• 初次分析后按物种或资源筛选结果
• 通过 URL 与协作者分享结果：https://reactome.org/PathwayBrowser/#/DTAB=AN&ANALYSIS={token}
• 令牌会在数小时后过期；如有需要，请重新提交基因列表

常见工作流

工作流 1：基因列表富集分析流程

目标：提交基因列表，获取富集通路，并探索排名靠前的结果。

import requests
import time

CONTENT = "https://reactome.org/ContentService"
ANALYSIS = "https://reactome.org/AnalysisService"

# Step 1: Submit gene list
genes = "TP53\nBRCA1\nBRCA2\nATM\nCHEK2\nCDK2\nRB1\nMDM2\nCDKN1A\nBAX"
resp = requests.post(
    f"{ANALYSIS}/identifiers/",
    headers={"Content-Type": "text/plain"},
    data=genes,
    params={"pageSize": 5, "sortBy": "ENTITIES_FDR", "order": "ASC"}
)
resp.raise_for_status()
result = resp.json()
token = result["summary"]["token"]
print(f"Token: {token} | Pathways found: {result['pathwaysFound']}")

# Step 2: Show top pathways with FDR
for p in result["pathways"][:5]:
    fdr = p["entities"]["fdr"]
    ratio = f"{p['entities']['found']}/{p['entities']['total']}"
    print(f"  {p['stId']}: {p['name']} (FDR={fdr:.2e}, {ratio})")
time.sleep(0.5)

# Step 3: Get details on top pathway
top_id = result["pathways"][0]["stId"]
detail = requests.get(f"{CONTENT}/data/query/{top_id}").json()
print(f"\nTop pathway: {detail['displayName']}")
print(f"Compartments: {[c['displayName'] for c in detail.get('compartment', [])]}")

工作流 2：通路探索

目标：从顶层通路逐步深入到特定反应和实体。

# Uses reactome_get helper and CONTENT base URL from Quick Start

# Step 1: Find pathway by search
results = reactome_get(CONTENT, "/search/query",
                       params={"query": "DNA repair", "types": "Pathway", "species": "Homo sapiens"})
top_hit = results["results"][0]["entries"][0]
pid = top_hit["stId"]
print(f"Found: {pid} — {top_hit['name']}")
time.sleep(0.5)

# Step 2: Get sub-events
events = reactome_get(CONTENT, f"/data/pathway/{pid}/containedEvents")
reactions = [e for e in events if e["schemaClass"] == "Reaction"]
subpaths = [e for e in events if "Pathway" in e["schemaClass"]]
print(f"Sub-pathways: {len(subpaths)}, Reactions: {len(reactions)}")
time.sleep(0.5)

# Step 3: Get participating molecules for a reaction
if reactions:
    rxn = reactions[0]
    refs = reactome_get(CONTENT, f"/data/participants/{rxn['stId']}/referenceEntities")
    print(f"\n{rxn['displayName']} participants:")
    for r in refs[:5]:
        print(f"  {r.get('databaseName', '?')}:{r.get('identifier', '?')} — {r['displayName']}")

工作流 3：表达数据分析

目标：连同标识符一起提交表达值，以叠加显示通路级别的表达数据。

import requests

ANALYSIS = "https://reactome.org/AnalysisService"

# Tab-separated: identifier \t expression_value1 \t expression_value2 ...
# First line can be a header (auto-detected)
expression_data = """#id\tcontrol\ttreated
TP53\t1.2\t3.5
BRCA1\t2.1\t1.8
CDK2\t0.9\t4.2
RB1\t1.5\t0.6
MDM2\t1.0\t2.8
CDKN1A\t0.8\t5.1
BAX\t1.1\t3.9"""

resp = requests.post(
    f"{ANALYSIS}/identifiers/",
    headers={"Content-Type": "text/plain"},
    data=expression_data,
    params={"pageSize": 10, "sortBy": "ENTITIES_FDR"}
)
resp.raise_for_status()
result = resp.json()

print(f"Expression columns: {result['summary'].get('sampleName', 'N/A')}")
print(f"Token: {result['summary']['token']}")
for p in result["pathways"][:3]:
    exp = p["entities"].get("exp", [])
    print(f"  {p['name']}: FDR={p['entities']['fdr']:.2e}, expr={exp}")

关键参数

参数	功能/端点	默认值	选项	效果
query	/search/query	—	任意字符串	关键词搜索词
types	/search/query	全部	Pathway、Reaction、Protein 等	按架构类筛选搜索结果
species	/search/query、分析	全部	物种名称或分类群 ID	限定到特定生物
pageSize	分析、搜索	20	1-250	每页结果数
sortBy	分析	ENTITIES_PVALUE	ENTITIES_FDR、ENTITIES_PVALUE、ENTITIES_FOUND、NAME	对富集结果排序
resource	分析筛选	TOTAL	TOTAL、UNIPROT、ENSEMBL、CHEBI 等	按标识符来源筛选
cluster	/search/query	true	true、false	按类型对搜索结果分组

最佳实践

1. 在连续请求之间使用 time.sleep(0.5)：Reactome 没有公布明确的速率限制，但连续快速请求可能会受到限制。请合理使用共享资源。

2. 保存并重复使用分析令牌：令牌在数小时内有效。保存令牌，以便按物种或资源重新筛选结果，而无需重新提交。

3. 优先使用稳定 ID，而非数据库 ID：Reactome 稳定 ID（R-HSA-69620）是永久的。内部数据库 ID 可能会随版本更新而变化。

4. 对富集结果使用 sortBy=ENTITIES_FDR：对于通路级别的显著性，经过 FDR 校正的 p 值比原始 p 值更可靠。

5. 检查分析结果中的 identifiersNotFound：未映射数量过多可能表示标识符类型错误或 ID 已过时。

常见示例

示例：获取通路中的所有基因

import requests

CONTENT = "https://reactome.org/ContentService"

pathway_id = "R-HSA-69620"  # Cell Cycle
refs = requests.get(f"{CONTENT}/data/participants/{pathway_id}/referenceEntities").json()
genes = set()
for r in refs:
    if r.get("databaseName") == "UniProt":
        genes.add(r.get("displayName", r.get("identifier")))
print(f"UniProt proteins in {pathway_id}: {len(genes)}")
for g in sorted(genes)[:10]:
    print(f"  {g}")

示例：通路图 URL

# Generate a direct link to the Reactome pathway diagram
pathway_id = "R-HSA-69620"
diagram_url = f"https://reactome.org/PathwayBrowser/#/{pathway_id}"
print(f"View diagram: {diagram_url}")

# With analysis overlay
token = "YOUR_TOKEN"
overlay_url = f"https://reactome.org/PathwayBrowser/#/{pathway_id}&DTAB=AN&ANALYSIS={token}"
print(f"View with analysis: {overlay_url}")

示例：批量通路查询

import requests
import time

CONTENT = "https://reactome.org/ContentService"

pathway_ids = ["R-HSA-69620", "R-HSA-109581", "R-HSA-1640170"]
summaries = []
for pid in pathway_ids:
    resp = requests.get(f"{CONTENT}/data/query/{pid}")
    resp.raise_for_status()
    data = resp.json()
    summaries.append({
        "stId": data["stId"],
        "name": data["displayName"],
        "species": data["speciesName"],
        "hasDiagram": data.get("hasDiagram", False)
    })
    time.sleep(0.5)

for s in summaries:
    print(f"{s['stId']}: {s['name']} (diagram: {s['hasDiagram']})")

故障排除

问题	原因	解决方案
404 Not Found	稳定 ID 无效或物种前缀错误	验证 ID 格式：人类使用 R-HSA-{number}；使用 /search/query 查找有效 ID
400 Bad Request	POST 请求正文格式错误或 Content-Type 错误	分析时使用 Content-Type: text/plain；标识符以换行符分隔
分析结果为空	无法识别标识符	检查 identifiersNotFound；尝试不同的 ID 类型（UniProt 与 HGNC 符号）
500 Internal Server Error	服务端问题或输入过大	稍后重试；将大型基因列表（>2000 个 ID）拆分为多个批次
令牌已过期	分析结果已不可用	重新提交基因列表；令牌有效期为数小时
物种结果错误	未应用物种筛选条件	在搜索/分析中添加 species=Homo sapiens 参数
响应缓慢	通路包含大量实体	使用 pageSize 分页；在本地缓存结果
交叉引用结果为空	实体没有外部数据库映射	并非所有 Reactome 实体都有 UniProt/Ensembl 映射；检查实体架构类

捆绑资源

此技能整合了以下内容：

• API 参考（465 行）：核心 API 模块 1-6 涵盖了内容服务端点（data/query、search、participants、通路层级、物种、xrefs）和分析服务端点（标识符、令牌检索、筛选）。支持的标识符类型见“关键概念”。响应格式详情和错误处理见“故障排除”。
• 查询脚本（286 行）：ReactomeClient 类方法（query_pathway、get_pathway_entities、search_pathways、analyze_genes、get_analysis_by_token）已整合到核心 API 代码块和常见工作流中。

相关技能

• kegg-database — KEGG 通路查询和代谢网络数据；适用于侧重代谢通路的场景和跨数据库 ID 转换
• string-database-ppi — 来自 STRING 的蛋白质-蛋白质相互作用网络；通过相互作用证据补充 Reactome 通路数据
• bioservices-multi-database — 统一的 Python 接口，可访问包括通过 bioservices.Reactome 使用的 Reactome 在内的 40 多个数据库
• cobrapy-metabolic-modeling — 基于约束的代谢建模；将 Reactome 通路数据用作 FBA 分析的输入

参考资料

• Reactome Content Service API — 交互式 API 文档（Swagger）
• Reactome Analysis Service API — 富集分析 API 文档
• Reactome website — 通路浏览器、图示查看器、物种比较
• reactome2py — Reactome API 的官方 Python 封装
• Gillespie, M. et al. (2022) "The reactome pathway knowledgebase 2022" Nucleic Acids Research 50:D364-D370