Reactome Database and Visualization Skill

A declarative, rate-limited command-line toolkit and interactive web dashboard generator for querying Reactome pathway knowledgebase, performing gene and protein overrepresentation analyses, navigating biological hierarchies, and exporting pathway diagrams.

---

Non-Technical Introduction: What is this skill and how do I use it?

Background Concepts

In biological research, genes and proteins rarely act alone. Instead, they work together in ordered sequences of biochemical reactions known as biological pathways (for example, DNA repair, cell division, or immune responses). When researchers conduct genetic experiments or clinical tests, they often produce a list of genes that appear active or altered.

The Reactome Database and Visualization Skill connects this list of genes to the Reactome knowledgebase. It identifies which biological systems are most affected, calculates statistical confidence scores, and produces interactive visual dashboards and diagrams.

How to Use This Skill: Three Everyday Examples

Example 1: Finding What Pathways a Single Gene is Involved In

If you want to know what biological processes a specific gene (such as TP53, the cellular tumor suppressor) participates in:

uv run reactome_database/scripts/reactome_analysis.py identifier \
  --id TP53 \
  --limit 5 \
  --output output/tp53_pathways.json

What this gives you: A file listing the top pathways containing TP53, such as Cell Cycle Checkpoints and Transcriptional Regulation.

Example 2: Analyzing a List of Genes from an Experiment

If a laboratory experiment identified several interesting genes (such as TP53, BRCA1, EGFR, MYC, PTEN), you can run an overrepresentation analysis to see which biological systems are significantly enriched:

uv run reactome_database/scripts/reactome_analysis.py analyze \
  --data "TP53,BRCA1,EGFR,MYC,PTEN,RB1,CDKN2A" \
  --fdr 0.05 \
  --output output/enrichment_results.json

What this gives you: A statistical summary filtering only pathways with a False Discovery Rate (FDR) below 5%, ensuring high statistical confidence.

Example 3: Creating a Visual Dashboard and Pathway Diagram

To turn your analysis results into an interactive visual dashboard with vector graphics that remain crisp at any zoom level:

# 1. Export the diagram in vector SVG format with your genes highlighted
uv run reactome_database/scripts/reactome_analysis.py diagram \
  --id R-HSA-6804754 \
  --highlight "TP53,MDM2" \
  --format svg \
  --output output/pathway_diagram.svg

# 2. Compile the interactive HTML dashboard with embedded vector diagram
uv run reactome_database/scripts/reactome_analysis.py dashboard \
  --input output/enrichment_results.json \
  --diagram output/pathway_diagram.svg \
  --output output/dashboard.html

What this gives you: An interactive web page with statistical bar charts, a searchable pathways table, a dark and light mode toggle, and an interactive pan and zoom vector pathway diagram that remains sharp at any magnification.

Using This Skill with AI Assistant Prompts

Non-technical users do not need to run terminal commands manually. When this skill is active in an enterprise agent harness (such as Gemini Enterprise), you can interact directly using natural language prompts.

Sample Prompts for Enterprise Agent Harnesses

• Scenario 1: Experimental Gene Signature and Overrepresentation Analysis

  "I have an RNA-Seq dataset with significantly upregulated genes: TP53, BRCA1, EGFR, MYC, PTEN, RB1, and CDKN2A. Please perform an overrepresentation analysis using the Reactome skill, apply an FDR filter of 0.05, and provide a summary of the top enriched biological pathways."

• Scenario 2: End-to-End Interactive Visual Dashboard Generation

  "Please analyze the gene list TP53, BRCA1, EGFR, MYC, PTEN with Reactome, export a pathway diagram for the top hit highlighting these genes, and generate a self-contained interactive web dashboard with statistical charts and sortable pathway tables."

• Scenario 3: Single Target Exploration and Pathway Mapping

  "Using the Reactome skill, look up the identifier EGFR and tell me the primary signaling pathways and cellular cascades it participates in for Homo sapiens."

• Scenario 4: Biochemical Reaction and Complex Tracing

  "Can you inspect the reaction 'Regulation of TP53 Expression' in Reactome and list all participating physical entities, complexes, and catalysts?"

• Scenario 5: Cross-Species Pathway Comparison

  "Compare the pathway coverage of the human cell cycle against Saccharomyces cerevisiae (Yeast, Taxon ID 4932) and summarize the major conserved processes."

---

Features

• High-Throughput Pathway Overrepresentation: Submit gene symbols, UniProt IDs, Ensembl IDs, or ChEBI identifiers with client-side FDR and p-value filtering.
• Analysis Token Management: Retrieve cached 7-day analysis results, filter by species, download CSV and JSON reports, or inspect unmapped identifiers.
• Biological Hierarchy Tracing: Navigate parent-child pathway trees, reaction mechanisms, catalyst and participant entities, and macromolecular complexes.
• Diagram Visualization: Render publication-ready pathway diagrams in PNG, SVG, JPG, or GIF formats with highlighted candidate hit entities.
• Interactive Web UI Dashboard: Generate self-contained, responsive HTML dashboards featuring dark and light mode toggles, statistical charts, sortable data tables, and embedded diagram viewers.
• Polite Rate Limiting: Built-in 1 QPS client rate limiting with exponential backoff and retry mechanisms to respect Reactome public infrastructure.

---

Project Structure and File Tree

.
├── LICENSE
├── README.md
├── dashboard_sample.html
├── assets/
│   └── workflow_overview.jpg
├── .licenses/
│   └── reactome_database_LICENSE.txt
└── reactome_database/
    ├── SKILL.md
    ├── references/
    │   ├── api_reference.md
    │   └── citation.bib
    └── scripts/
        ├── dashboard_template.py
        └── reactome_analysis.py

Component Breakdown

• LICENSE: The complete Apache License Version 2.0 terms.
• README.md: Project documentation, non-technical introduction, and quickstart commands.
• dashboard_sample.html: Pre-compiled, standalone sample dashboard to preview interactive functionality without running scripts.
• assets/: Image assets and diagrams used for documentation.
• .licenses/: Local directory recording terms of use acknowledgement.
• reactome_database/SKILL.md: Skill instructions, biological species taxonomy IDs, common pathway identifiers, and multi-step recipes.
• reactome_database/references/api_reference.md: Detailed documentation of all 15 service domains and CLI commands.
• reactome_database/references/citation.bib: BibTeX academic citation reference.
• reactome_database/scripts/reactome_analysis.py: Declarative CLI executable with 1 QPS rate limiting and dynamic subcommand dispatching.
• reactome_database/scripts/dashboard_template.py: Self-contained HTML/CSS/JS interactive dashboard generator.

---

Quickstart

Prerequisites

• Python >= 3.10
• uv package manager

1. Check Database Information

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

2. Single Identifier Analysis

uv run reactome_database/scripts/reactome_analysis.py identifier \
  --id TP53 \
  --limit 5 \
  --output output/tp53_pathways.json

3. Batch Pathway Enrichment Analysis

uv run reactome_database/scripts/reactome_analysis.py analyze \
  --data "TP53,BRCA1,EGFR,MYC,PTEN,RB1,CDKN2A,MDM2,ATM,CHEK2" \
  --fdr 0.05 \
  --output output/enrichment.json

4. Export Pathway Diagram (Vector SVG)

uv run reactome_database/scripts/reactome_analysis.py diagram \
  --id R-HSA-6804754 \
  --highlight "TP53,MDM2" \
  --format svg \
  --output output/pathway_diagram.svg

5. Generate Interactive Visual Web Dashboard

uv run reactome_database/scripts/reactome_analysis.py dashboard \
  --input output/enrichment.json \
  --diagram output/pathway_diagram.svg \
  --output output/dashboard.html

---

Reference Documentation

• SKILL.md: Complete skill instructions and biological reference guide.
• API Reference: Endpoint specifications across all 15 domains.
• Citation: Academic BibTeX citation for Reactome.

---

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for the full license text.

Reactome data and web services are open-access and freely available under the Creative Commons Attribution 4.0 International (CC BY 4.0) license. For more information, visit Reactome License Terms and Reactome Citations.