Metadata-Version: 2.4
Name: alphagenome-viewer
Version: 1.0.1
Summary: Web interface for Google DeepMind's AlphaGenome genomic prediction model
Author-email: Abrar Abir <abir@cmu.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Abrar-Abir/alphagenome-viewer
Project-URL: Repository, https://github.com/Abrar-Abir/alphagenome-viewer
Keywords: genomics,alphagenome,deepmind,variant-effect,bioinformatics,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: alphagenome>=0.5.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-multipart>=0.0.6
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/Abrar-Abir/alphagenome-viewer/main/frontend/public/logo.png" alt="AlphaGenome Viewer" width="280">
</p>

<p align="center">
  A web interface for Google DeepMind's <a href="https://deepmind.google/blog/alphagenome-ai-for-better-understanding-the-genome/">AlphaGenome</a> genomic prediction model.
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> &middot;
  <a href="#features">Features</a> &middot;
  <a href="#deployment">Deployment</a> &middot;
  <a href="#license">License</a>
</p>

---

## What is this?

AlphaGenome Viewer gives you a point-and-click interface to query AlphaGenome predictions — no notebook or SDK boilerplate required. Enter a genomic region or variant, pick your output types and tissues, and get back publication-ready plots and scores in seconds.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Abrar-Abir/alphagenome-viewer/main/docs/dark_mode.png">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Abrar-Abir/alphagenome-viewer/main/docs/light_mode.png">
    <img alt="AlphaGenome Viewer screenshot" src="https://raw.githubusercontent.com/Abrar-Abir/alphagenome-viewer/main/docs/light_mode.png" width="700">
  </picture>
</p>

## Features

**Interval Predictions** — Visualize gene expression, chromatin accessibility, histone marks, and more across any genomic region.

**Variant Effect Comparison** — Overlay REF vs ALT predictions side-by-side to see exactly how a variant changes the signal.

**Variant Scoring** — Score variants with AlphaGenome's recommended scorers and get quantile rankings across the genome.

### Supported output types

| Category | Types |
|----------|-------|
| Expression | RNA-seq, CAGE, PRO-cap |
| Accessibility | ATAC-seq, DNase-seq |
| Chromatin | ChIP-seq (histones), ChIP-seq (TFs), Contact maps |
| Splicing | Splice sites, Splice site usage, Splice junctions |

## Quick Start

### Option A: pip install (simplest)

```bash
pip install alphagenome-viewer
alphagenome-viewer
```

Open **http://localhost:8000** and enter your API key when prompted. The command accepts `--port`, `--host`, `--workers`, and `--plots-dir` flags.

### Option B: From source

#### Prerequisites

- Python 3.10+
- Node.js 18+
- [AlphaGenome API key](https://aistudio.google.com/apikey)

#### Install & Run

```bash
# Clone the repo
git clone https://github.com/Abrar-Abir/alphagenome-viewer.git
cd alphagenome-viewer

# Install dependencies
cd backend && pip install -r requirements.txt && cd ..
cd frontend && npm install && cd ..

# Start both services
./start.sh
```

You should see output like this:

```
Starting AlphaGenome Viewer...

Starting backend on http://localhost:8000...
Backend started (PID 20094, logging to backend/app.log)
Starting frontend on http://localhost:5173...
Frontend started (PID 20134, logging to frontend/app.log)

Both services running. Press Ctrl+C to stop.
  Backend:  http://localhost:8000 (logs: backend/app.log)
  Frontend: http://localhost:5173 (logs: frontend/app.log)
```

Open **http://localhost:5173** and enter your API key when prompted. That's it.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Abrar-Abir/alphagenome-viewer/main/docs/dialog_dark.png">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Abrar-Abir/alphagenome-viewer/main/docs/dialog_light.png">
    <img alt="API key setup dialog" src="https://raw.githubusercontent.com/Abrar-Abir/alphagenome-viewer/main/docs/dialog_light.png" width="400">
  </picture>
</p>

Press `Ctrl+C` to stop both services:

```
^C
Shutting down...
[2]+  Terminated              npm run dev > app.log 2>&1
Shutdown complete.
```

> You can also run the services separately — see [backend/README.md](backend/README.md) and [frontend/README.md](frontend/README.md) for details.

## Deployment

### Docker

```bash
docker compose up
```

Open **http://localhost:8000**. Generated plots persist across restarts via a Docker volume. Your API key is stored in your browser's localStorage.

To build and run manually:

```bash
docker build -t alphagenome-viewer .
docker run -p 8000:8000 -v agplots:/app/data/plots alphagenome-viewer
```

### Apptainer / Singularity

For shared servers or HPC environments, build a single container — no Node.js needed at runtime:

```bash
apptainer build alphagenome-viewer.sif alphagenome-viewer.def

mkdir -p ./data/plots
apptainer run \
    --bind ./data/plots:/opt/alphagenome-viewer/data/plots \
    alphagenome-viewer.sif
```

Open **http://localhost:8000**. Change the port with `APPTAINERENV_AGVIEWER_PORT=9000`.

See `apptainer run-help alphagenome-viewer.sif` for the full list of environment variables and bind mount paths.

## Tech Stack

- **Frontend**: React, Vite, Tailwind CSS, shadcn/ui
- **Backend**: FastAPI, Matplotlib
- **API**: [AlphaGenome SDK](https://github.com/google-deepmind/alphagenome)

## Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

## License

[MIT](LICENSE)

This project uses open-source dependencies under their own licenses. See [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES) for details.
