/reactome_database

name: reactome-database
description: >
  Query the Reactome database (Analysis and Content Services). Use when the user
  asks about pathway analysis, gene list enrichment, retrieving results by
  token, finding unmapped or not-found identifiers, mapping identifiers,
  reaction participants (inputs, outputs), pathway hierarchy (including
  top-level pathways), diagram export, cross-reference mapping, or searching the
  knowledgebase.

Reactome Analysis & Content Service

Prerequisites

1. **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure `uv` is installed and on PATH. 2. **User Notification**: If .licenses/reactome_database_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://reactome.org/license and https://reactome.org/cite, then (2) create the file recording the notification text and timestamp.

Overview

Reactome is a free, open-source, curated pathway database. This skill wraps both the **Analysis Service** (`https://reactome.org/AnalysisService/`) and the **Content Service** (`https://reactome.org/ContentService/`) providing pathway enrichment analysis, identifier mapping, reaction details, pathway hierarchy navigation, diagram export, cross-reference mapping, and search.

When to Use This Skill

• Performing pathway enrichment (overrepresentation) analysis on gene/protein

lists

• Retrieving analysis results using a token from previous enrichment
• Identifying which genes or proteins were not found in a pathway analysis
• Analyzing gene expression data against pathway annotations
• Mapping identifiers to Reactome entities across species
• Retrieving reaction participants (inputs, outputs, catalysts, regulators)
• Navigating pathway hierarchy and listing top-level pathways
• Finding which complexes or sets contain a protein
• Exporting pathway/reaction diagrams (PNG/SVG) with gene highlighting
• Cross-referencing identifiers across databases (UniProt, Ensembl, etc.)
• Searching the Reactome knowledgebase
• Downloading analysis reports (PDF, CSV, JSON)
• Comparing pathways across species

Common Species IDs

Reference list for common research organisms:

• Homo sapiens
• ID: 9606
• Mus musculus (Mouse)
• ID: 48892
• Rattus norvegicus (Rat)
• ID: 48895

Common Pathway IDs

Reference list for commonly used Reactome pathway stable IDs:

• Cell Cycle
• Stable ID: R-HSA-1640170
• Notes: Top-level pathway (broad)
• Cell Cycle, Mitotic
• Stable ID: R-HSA-69278
• Notes: Specific sub-pathway — use this for diagrams and drill-downs
• Immune System
• Stable ID: R-HSA-168256
• Notes: Top-level pathway
• Signal Transduction
• Stable ID: R-HSA-162582
• Notes: Top-level pathway
• Gene Expression
• Stable ID: R-HSA-74160
• Notes: Top-level pathway
• Programmed Cell Death
• Stable ID: R-HSA-5357801
• Notes: Top-level pathway

> **Important**: When the user asks for a "Cell Cycle" diagram or analysis, > prefer the specific **Cell Cycle, Mitotic** pathway (`R-HSA-69278`) unless the > user explicitly requests the top-level overview. The examples throughout this > document use `R-HSA-69278`.

Core Rules

1. **Always use `--output`**: Every subcommand requires `--output <file>` to write results to a file. Never rely on stdout for large results. 2. **Default species is Homo sapiens**: Use `--species` to override. 3. **Tokens expire after 7 days**: Store tokens from analysis results to retrieve them later without re-submitting data. 4. **Use `--fdr` and `--pvalue` to filter**: Enrichment results can be overwhelming. Filter with `--fdr 0.05` or `--pvalue 0.01` to focus on statistically significant pathways. 5. **Identifier formats**: Reactome auto-detects identifiers including gene symbols (TP53), UniProt (P04637), Ensembl (ENSG00000141510), ChEBI, OMIM, EntrezGene, and many more. 6. **Handle large outputs**: For commands that return large data (like `species-comparison`), use the `--summary` flag to truncate lists and avoid exceeding workspace file size limits (1MB). 7. **Notification**: If this skill is used, ensure this is mentioned in the output.

Tool Execution

The CLI tool is at `scripts/reactome_analysis.py`. Run with `uv`:

uv run scripts/reactome_analysis.py <command> [options] --output /tmp/out.json

**To list all available subcommands and flags**, run:

uv run scripts/reactome_analysis.py --help

Use `--help` to verify available subcommands or flags before executing an unfamiliar command.

Feature Domains

1. Database Info

uv run scripts/reactome_analysis.py db-version --output /tmp/version.json
uv run scripts/reactome_analysis.py db-name --output /tmp/name.json

2. Single Identifier Analysis

uv run scripts/reactome_analysis.py identifier --id TP53 --output /tmp/tp53.json
uv run scripts/reactome_analysis.py identifier-projection --id TP53 --output /tmp/tp53_proj.json

3. Batch Analysis (Enrichment)

Submit a list of identifiers for overrepresentation or expression analysis:

uv run scripts/reactome_analysis.py analyze --data "TP53,BRCA1,EGFR" --output /tmp/enrich.json
uv run scripts/reactome_analysis.py analyze --file genes.txt --output /tmp/enrich.json
uv run scripts/reactome_analysis.py analyze-projection --data "TP53,BRCA1" --output /tmp/proj.json
uv run scripts/reactome_analysis.py analyze --data "TP53,BRCA1" --fdr 0.05 --output /tmp/sig.json

Common options: `--page-size` (alias `--limit`), `--page` (alias `--offset`), `--sort-by`, `--order`, `--resource`, `--species`, `--fdr`, `--pvalue`.

4. Token-Based Result Retrieval

uv run scripts/reactome_analysis.py token-result --token TOKEN --output /tmp/result.json
uv run scripts/reactome_analysis.py token-not-found --token TO