BEERE is a web-based bioinformatics tool that helps researchers characterize gene/protein lists and biomedical terms via network-based ranking and interactive visualization.
Version 2.0 is a complete modernization of the original BEERE platform, rebuilt with Next.js, React, and an AI-powered research assistant.
Original Publication: Zongliang Yue, Christopher D Willey, Anita B Hjelmeland, Jake Y Chen. BEERE: a web server for biomedical entity expansion, ranking and explorations. Nucleic Acids Research, Volume 47, Issue W1, 02 July 2019, Pages W578–W586. https://doi.org/10.1093/nar/gkz428
The original PHP/CodeIgniter v1 codebase is archived at aimed-lab/BEERE-dev.
| Landing Page | Pipeline — Entity Input |
|---|---|
 |
 |
| AI Chat Panel | 5-Step Pipeline Overview |
|---|---|
 |
 |
- Modern React UI — Next.js 14 App Router with shadcn/ui components and Tailwind CSS
- AI Research Assistant — Claude-powered chat panel with PubMed literature search via MCP
- WebGL Network Visualization — sigma.js v2 with graphology for rendering large PPI networks
- Real-time Streaming — Server-Sent Events for AI chat responses
- Dark Mode — Full light/dark theme support
- Export — PNG/SVG network export, CSV ranking export
- Same Proven Pipeline — The 5-step BEERE analysis pipeline is faithfully preserved
┌─────────────────────────────────────────────────────────┐
│ Nginx (reverse proxy) │
├─────────────────────────┬───────────────────────────────┤
│ Next.js 14 (port 3000) │ Django Ranking (port 8001) │
│ - React UI (App Router)│ - PageRank algorithm │
│ - API Routes (BFF) │ - Ant-Colony algorithm │
│ - AI Chat streaming │ - Statistical evaluation │
│ - Oracle queries │ │
├─────────────────────────┴───────────────────────────────┤
│ Oracle 12g (BEERE_web_access — SELECT only) │
│ HAPPI 2.0 | SemMedDB | NCBI Gene | PubTator │
├─────────────────────────────────────────────────────────┤
│ PubMed MCP Server Anthropic API (Claude) │
└─────────────────────────────────────────────────────────┘
- Node.js 20+ and npm
- Oracle 12g+ database with the BEERE schema (HAPPI, SemMedDB, NCBI Gene tables)
- Python 3.8+ for the Django ranking API (existing service)
- Anthropic API key for the AI chat feature
- Docker & Docker Compose (for production deployment)
# 1. Clone the repository
git clone https://github.com/aimed-lab/BEERE.git
cd BEERE/frontend
# 2. Install dependencies
npm install
# 3. Configure environment
cp .env.example .env
# Edit .env with your Oracle credentials and Anthropic API key
# 4. Start the development server
npm run devOpen http://localhost:3000 to access the application.
BEERE connects to an Oracle 12g+ database using the oracledb driver in Thin mode (pure JavaScript — no Oracle Instant Client required).
- Copy
.env.exampleto.env - Set your Oracle credentials:
ORACLE_USER=BEERE_web_access ORACLE_PASSWORD=<your-password> ORACLE_CONNECT_STRING=discovery.informatics.uab.edu:1521/beere - The
BEERE_web_accessaccount should have SELECT privileges on:- HAPPI 2.0 PPI tables (protein-protein interactions)
- SemMedDB tables (semantic predications, concepts)
- NCBI Gene tables (symbols, aliases)
- PubTator annotations (gene-to-PMID mappings)
The ranking algorithms (PageRank, Ant-Colony) run in the existing Python/Django service:
DJANGO_API_URL=http://localhost:8001
If running the Django service separately, ensure it's accessible at the configured URL.
To enable the AI research assistant:
ANTHROPIC_API_KEY=sk-ant-your-key-here
Get an API key at console.anthropic.com.
# 1. Configure environment
cp frontend/.env.example frontend/.env
# Edit frontend/.env with production credentials
# 2. Build and start all services
docker compose up -d
# 3. Access at http://your-server (port 80 via nginx)| Service | Port | Description |
|---|---|---|
frontend |
3000 | Next.js application (API routes + React UI) |
django |
8001 | Python ranking API (PageRank, Ant-Colony) |
nginx |
80/443 | Reverse proxy with SSE support for chat |
docker-compose.yml— Production configurationdocker-compose.dev.yml— Development with hot-reload and volume mounts
BEERE implements a 5-step analysis pipeline:
- Gene mode: Paste gene symbols or IDs, set PPI confidence threshold (3-star/4-star/5-star), toggle network expansion
- Term mode: Paste biomedical terms or UMLS CUIs, set RDS threshold, select predicates
- Verifies input entities against HAPPI 2.0 and NCBI Gene databases
- Shows matched/unmatched/expanded entities with S/E tags
- Users can correct or remove matches before proceeding
- Retrieves quality-controlled relationships from the database
- Displays IOA (Index of Aggregation) and SCN (Seed Coverage in Network) metrics
- Configure: iteration count, ranking method, sigma (restart probability)
- Ranks entities using PageRank or Ant-Colony optimization
- Displays: ranking score, rank, adjusted P-value, significance level
- Interactive word cloud and ranking histogram visualizations
- WebGL-rendered interactive network graph (sigma.js v2)
- Layout algorithms: Force-Directed, DEMA, Circular
- Node/edge click for details, hover for neighbor highlighting
- Provenance panel with PubMed references
- Export to PNG/SVG, download rankings as CSV
- Docked on the right side, available throughout all pipeline steps
- Context-aware: knows your current step, entities, and ranking method
- Can search PubMed for relevant literature
- Explains BEERE metrics (IOA, SCN, RDS, P-values)
| Layer | Technology |
|---|---|
| Frontend | Next.js 14 (App Router), React 18, TypeScript 5 |
| UI Components | shadcn/ui + Tailwind CSS v4 |
| State Management | Zustand (pipeline) + TanStack Query (server data) |
| Network Graph | sigma.js v2 + graphology (WebGL) |
| Charts | D3.js (histogram), wordcloud2.js (word cloud) |
| Database | oracledb v6 Thin mode (pure JS, no native deps) |
| AI Chat | Vercel AI SDK + @ai-sdk/anthropic (Claude) |
| Literature | PubMed MCP Server |
| Deployment | Docker Compose + Nginx |
BEERE/
├── frontend/ # Next.js application
│ ├── src/
│ │ ├── app/ # App Router pages + API routes
│ │ │ ├── pipeline/ # 5-step pipeline pages
│ │ │ └── api/ # BFF API routes (Oracle, Django proxy, chat)
│ │ ├── components/ # React components
│ │ │ ├── ui/ # shadcn/ui primitives
│ │ │ ├── pipeline/ # Pipeline-specific components
│ │ │ └── chat/ # AI chat components
│ │ ├── lib/ # Utilities, hooks, stores, services
│ │ └── types/ # TypeScript type definitions
│ ├── Dockerfile
│ └── package.json
├── nginx/ # Nginx reverse proxy config
├── docker-compose.yml # Production Docker Compose
├── docker-compose.dev.yml # Development Docker Compose
└── README.md
| Term | Definition |
|---|---|
| IOA | Index of Aggregation — nodes in largest connected component / total nodes |
| SCN | Seed Coverage in Network — connected seed nodes / total seed nodes |
| PPI Confidence | HAPPI 2.0 quality score: 3-star (0.45), 4-star (0.75), 5-star (0.9) |
| RDS | Relation Density Score — statistical significance of term-to-term relationships |
| PageRank | Iterative ranking capturing global importance in the network |
| Ant Colony | Optimization algorithm for entity prioritization |
| Sigma | Restart probability parameter for ranking (0–1, default 0.8) |
If you use BEERE in your research, please cite:
@article{yue2019beere,
title={BEERE: a web server for biomedical entity expansion, ranking and explorations},
author={Yue, Zongliang and Willey, Christopher D and Hjelmeland, Anita B and Chen, Jake Y},
journal={Nucleic Acids Research},
volume={47},
number={W1},
pages={W578--W586},
year={2019},
publisher={Oxford University Press},
doi={10.1093/nar/gkz428}
}MIT License. See LICENSE for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes
- Push to the branch (
git push origin feature/your-feature) - Open a Pull Request