# google-deepmind/alphagenome architecture

> Architecture diagram of the GitHub repository google-deepmind/alphagenome, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-deepmind/alphagenome
- Repository: https://github.com/google-deepmind/alphagenome

## Overview

1. **What this repository is**
   - This is a **client-side Python SDK** for the AlphaGenome API, plus documentation, notebooks, and helper utilities.
   - It does **not** contain the core model weights or training code; the main runtime boundary is a **remote AlphaGenome service** accessed with an API key.

2. **Top-level architecture**
   - The code is organized around four functional layers:
     - **Data/domain objects** for genomic coordinates and annotations.
     - **Model client and scoring logic** for remote prediction calls.
     - **Interpretation utilities** for variant effect analysis.
     - **Visualization utilities** for rendering outputs.
   - Supporting layers include **protobuf/gRPC definitions**, **tensor utilities**, **docs/notebooks**, and a small **script** for reference data preprocessing.

3. **Core data model layer**
   - `src/alphagenome/data` defines the repository’s shared genomic vocabulary:
     - intervals, variants, genomes, transcripts, gene annotations, ontology terms, junctions, track data, and fold intervals.
   - These objects are the primary inputs and metadata carriers used throughout the rest of the package.
   - The repository also ships reference annotation support, including a modified GENCODE-derived dataset for illustrative use.

4. **Model access layer**
   - `src/alphagenome/models` is the main integration point with the AlphaGenome service.
   - `dna_client.py` is the entry point used by users to create a client with an API key.
   - `dna_model.py`, `dna_output.py`, and the scorer modules wrap remote predictions into structured outputs and provide higher-level APIs for:
     - whole-interval scoring,
     - variant scoring,
     - output selection,
     - and post-processing of returned predictions.

5. **Remote service boundary**
   - `src/alphagenome/protos` contains the protobuf contracts for the client/server interface.
   - The presence of `dna_model_service.proto` and `dna_model.proto` indicates a **typed RPC boundary** between this SDK and the hosted inference service.
   - This is the key architectural seam: the local library marshals inputs, sends requests over RPC, and converts returned tensors/structured outputs back into Python objects.

6. **Prediction and scoring flow**
   - The typical flow is:
     - user supplies an interval, variant, and optional ontology terms,
     - the client sends these to the remote model service,
     - the service returns multimodal predictions,
     - the SDK packages them as reference/alternate outputs for downstream analysis.
   - Variant-oriented modules support comparison between REF and ALT predictions, which is central to the repository’s “variant effect” use case.

7. **Interpretation layer**
   - `src/alphagenome/interpretation/ism.py` provides **in silico mutagenesis (ISM)** support.
   - This layer sits on top of the model outputs and is meant for explanation/attribution-style analysis rather than raw prediction.
   - It depends on the model/data layers and produces analysis artifacts that can be used in notebooks or downstream workflows.

8. **Visualization layer**
   - `src/alphagenome/visualization` turns predictions and annotations into `matplotlib` figures.
   - `plot.py`, `plot_components.py`, and `plot_transcripts.py` suggest a composable plotting system for:
     - overlaid tracks,
     - transcript-centric views,
     - variant markers,
     - and modality-specific prediction displays.
   - This layer consumes model outputs and data objects, but is otherwise isolated from the RPC service.

9. **Utility and support code**
   - `tensor_utils.py` and `typing.py` provide internal infrastructure for tensor shaping, validation, and type safety across the package.
   - `colab_utils.py` supports notebook workflows, which are a first-class part of the user experience for this repo.

10. **Data preparation script**
   - `scripts/process_gtf.py` is a preprocessing utility for GTF-style gene annotation data.
   - It is separate from the SDK runtime and appears aimed at building or transforming reference annotations used by the data layer.

11. **Examples and user workflows**
   - The `colabs/` notebooks show the intended usage patterns:
     - quick start,
     - batch variant scoring,
     - splicing analysis,
     - tissue ontology mapping,
     - visualization tours,
     - and full analysis workflows.
   - These notebooks are effectively the application-layer examples that stitch together data loading, prediction, interpretation, and plotting.

12. **Documentation and delivery**
   - `docs/` is built with Sphinx and mirrors the package’s public architecture: installation, API reference, tutorials, FAQs, and visualization guides.
   - CI is handled through GitHub Actions (`presubmit_checks.yml`, `release.yaml`), and packaging/testing is managed with `pyproject.toml`, `hatch`, `pytest`, and linting config.
   - The repo is designed as a distributable Python package rather than a server or standalone application.

13. **Important architectural takeaway**
   - The repository is best diagrammed as a **Python client SDK** with:
     - a **domain model layer** for genomic concepts,
     - a **typed RPC client layer** to a hosted AlphaGenome inference service,
     - **post-processing/interpretation utilities** on top of the predictions,
     - and **visualization/documentation examples** for end users.
   - Most dependencies flow outward from the data objects into model calls, then into interpretation and plotting; the only external runtime dependency is the AlphaGenome API endpoint itself.

Main entry points: [`src/alphagenome/data/__init__.py`](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/__init__.py) (Genomic data), [`src/alphagenome/visualization/plot.py`](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/visualization/plot.py) (Plotting), [`src/alphagenome/models/dna_model.py`](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/dna_model.py) (Model wrapper), [`colabs/quick_start.ipynb`](https://github.com/google-deepmind/alphagenome/blob/main/colabs/quick_start.ipynb) (Colabs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_data["Data domain"]
  node_data_core["Genomic data<br/>domain layer<br/>[__init__.py]"]
  node_genome["Genome<br/>reference data<br/>[genome.py]"]
  node_transcript["Transcripts<br/>annotation model<br/>[transcript.py]"]
  node_gene_annotation["Gene annotations<br/>annotation model<br/>[gene_annotation.py]"]
  node_ontology["Ontology terms<br/>metadata model<br/>[ontology.py]"]
  node_track_data["Track data<br/>signal model<br/>[track_data.py]"]
  node_junction_data["Junctions<br/>signal model<br/>[junction_data.py]"]
  node_fold_intervals["Fold intervals<br/>split metadata<br/>[fold_intervals.py]"]
end

subgraph group_group_models["Model access"]
  node_dna_client["Client entry<br/>API client<br/>[dna_client.py]"]
  node_dna_model["Model wrapper<br/>remote model<br/>[dna_model.py]"]
  node_dna_output["Model outputs<br/>output model<br/>[dna_output.py]"]
  node_interval_scorers["Interval scoring<br/>scoring API"]
  node_variant_scorers["Variant scoring<br/>scoring API<br/>[variant_scorers.py]"]
  node_track_utils["Track utilities<br/>adapter"]
  node_junction_utils["Junction utilities<br/>adapter"]
end

subgraph group_group_interpretation["Interpretation"]
  node_ism["ISM<br/>interpretation<br/>[ism.py]"]
end

subgraph group_group_visualization["Visualization"]
  node_plot["Plotting<br/>visualization<br/>[plot.py]"]
  node_plot_components["Plot components<br/>visualization<br/>[plot_components.py]"]
  node_plot_transcripts["Transcript plots<br/>visualization"]
end

subgraph group_group_support["Support"]
  node_protos["RPC protos<br/>service contract"]
  node_tensor_utils["Tensor utils<br/>infrastructure<br/>[tensor_utils.py]"]
  node_typing["Typing<br/>infrastructure<br/>[typing.py]"]
  node_colab_utils["Colab utils<br/>notebook support<br/>[colab_utils.py]"]
  node_process_gtf["GTF processing<br/>script<br/>[process_gtf.py]"]
end

subgraph group_group_examples["Examples and docs"]
  node_notebooks["Colabs<br/>examples<br/>[quick_start.ipynb]"]
  node_docs["Docs<br/>documentation<br/>[index.md]"]
end

node_repo_root["AlphaGenome SDK<br/>Python package"]
node_remote_service(("AlphaGenome API<br/>external service"))

node_repo_root -->|"defines"| node_data_core
node_repo_root -->|"provides"| node_dna_client
node_repo_root -->|"includes"| node_ism
node_repo_root -->|"includes"| node_plot
node_repo_root -->|"ships"| node_protos
node_repo_root -->|"supports"| node_colab_utils
node_data_core -->|"contains"| node_genome
node_data_core -->|"contains"| node_transcript
node_data_core -->|"contains"| node_gene_annotation
node_data_core -->|"contains"| node_ontology
node_data_core -->|"contains"| node_track_data
node_data_core -->|"contains"| node_junction_data
node_data_core -->|"contains"| node_fold_intervals
node_dna_client -->|"creates"| node_dna_model
node_dna_model -->|"calls"| node_protos
node_dna_model -->|"invokes"| node_remote_service
node_dna_model -->|"returns"| node_dna_output
node_interval_scorers -->|"uses"| node_dna_model
node_variant_scorers -->|"uses"| node_dna_model
node_variant_scorers -->|"compares"| node_dna_output
node_track_utils -->|"adapts"| node_track_data
node_junction_utils -->|"adapts"| node_junction_data
node_ism -->|"analyzes"| node_dna_output
node_ism -->|"builds on"| node_variant_scorers
node_plot -->|"composes"| node_plot_components
node_plot -->|"specializes"| node_plot_transcripts
node_plot -->|"renders"| node_dna_output
node_plot -->|"renders"| node_data_core
node_colab_utils -->|"supports"| node_notebooks
node_process_gtf -->|"prepares"| node_gene_annotation
node_docs -->|"documents"| node_plot
node_docs -->|"documents"| node_dna_client
node_docs -->|"documents"| node_ism
node_notebooks -->|"uses"| node_dna_client
node_notebooks -->|"uses"| node_variant_scorers
node_notebooks -->|"uses"| node_plot
node_notebooks -->|"uses"| node_ism

click node_data_core "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/__init__.py"
click node_genome "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/genome.py"
click node_transcript "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/transcript.py"
click node_gene_annotation "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/gene_annotation.py"
click node_ontology "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/ontology.py"
click node_track_data "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/track_data.py"
click node_junction_data "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/junction_data.py"
click node_fold_intervals "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/fold_intervals.py"
click node_dna_client "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/dna_client.py"
click node_dna_model "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/dna_model.py"
click node_dna_output "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/dna_output.py"
click node_interval_scorers "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/interval_scorers.py"
click node_variant_scorers "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/variant_scorers.py"
click node_track_utils "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/track_data_utils.py"
click node_junction_utils "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/junction_data_utils.py"
click node_ism "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/interpretation/ism.py"
click node_plot "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/visualization/plot.py"
click node_plot_components "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/visualization/plot_components.py"
click node_plot_transcripts "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/visualization/plot_transcripts.py"
click node_protos "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/protos/dna_model_service.proto"
click node_tensor_utils "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/tensor_utils.py"
click node_typing "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/typing.py"
click node_colab_utils "https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/colab_utils.py"
click node_process_gtf "https://github.com/google-deepmind/alphagenome/blob/main/scripts/process_gtf.py"
click node_notebooks "https://github.com/google-deepmind/alphagenome/blob/main/colabs/quick_start.ipynb"
click node_docs "https://github.com/google-deepmind/alphagenome/blob/main/docs/source/index.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_data_core,node_genome,node_transcript,node_gene_annotation,node_ontology,node_track_data,node_junction_data,node_fold_intervals toneBlue
class node_dna_client,node_dna_model,node_dna_output,node_interval_scorers,node_variant_scorers,node_track_utils,node_junction_utils toneAmber
class node_ism toneMint
class node_plot,node_plot_components,node_plot_transcripts toneRose
class node_protos,node_tensor_utils,node_typing,node_colab_utils,node_process_gtf toneIndigo
class node_notebooks,node_docs toneTeal
class node_repo_root,node_remote_service toneNeutral
```

## Components

### Data domain

Shared genomic entities and reference annotations

- [Genomic data](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/__init__.py): domain layer · Shared genomic vocabulary for intervals, variants, transcripts, genes, ontology, junctions, and tracks · `src/alphagenome/data/__init__.py`
- [Genome](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/genome.py): reference data · Genome coordinate and reference sequence abstractions · `src/alphagenome/data/genome.py`
- [Transcripts](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/transcript.py): annotation model · Transcript-centric annotations and structures · `src/alphagenome/data/transcript.py`
- [Gene annotations](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/gene_annotation.py): annotation model · Gene-level annotation structures and derived metadata · `src/alphagenome/data/gene_annotation.py`
- [Ontology terms](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/ontology.py): metadata model · Tissue or functional ontology mapping objects · `src/alphagenome/data/ontology.py`
- [Track data](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/track_data.py): signal model · Per-position or per-interval track containers used across scoring and plotting · `src/alphagenome/data/track_data.py`
- [Junctions](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/junction_data.py): signal model · Splice junction and junction-like data structures · `src/alphagenome/data/junction_data.py`
- [Fold intervals](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/data/fold_intervals.py): split metadata · Interval partitioning helpers for evaluation and dataset splits · `src/alphagenome/data/fold_intervals.py`

### Model access

Client, scoring, and RPC-facing prediction wrappers

- [Client entry](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/dna_client.py): API client · User-facing entry point for creating authenticated service clients · `src/alphagenome/models/dna_client.py`
- [Model wrapper](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/dna_model.py): remote model · High-level wrapper around remote AlphaGenome prediction calls · `src/alphagenome/models/dna_model.py`
- [Model outputs](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/dna_output.py): output model · Structured containers for returned predictions and selected outputs · `src/alphagenome/models/dna_output.py`
- [Interval scoring](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/interval_scorers.py): scoring API · Whole-interval scoring and post-processing over remote predictions · `src/alphagenome/models/interval_scorers.py`
- [Variant scoring](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/variant_scorers.py): scoring API · REF/ALT comparison and variant-effect scoring workflows · `src/alphagenome/models/variant_scorers.py`
- [Track utilities](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/track_data_utils.py): adapter · Helpers that map track data to model input/output structures · `src/alphagenome/models/track_data_utils.py`
- [Junction utilities](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/models/junction_data_utils.py): adapter · Helpers that map junction data into scoring and model workflows · `src/alphagenome/models/junction_data_utils.py`

### Interpretation

Post-processing and attribution utilities

- [ISM](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/interpretation/ism.py): interpretation · In silico mutagenesis for attribution-style variant analysis · `src/alphagenome/interpretation/ism.py`

### Visualization

Plotting and figure composition

- [Plotting](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/visualization/plot.py): visualization · Top-level figure assembly for model outputs and annotations · `src/alphagenome/visualization/plot.py`
- [Plot components](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/visualization/plot_components.py): visualization · Composable primitives for tracks, markers, and overlays · `src/alphagenome/visualization/plot_components.py`
- [Transcript plots](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/visualization/plot_transcripts.py): visualization · Transcript-centric plotting helpers and specialized layouts · `src/alphagenome/visualization/plot_transcripts.py`

### Support

Shared utilities, scripts, and service contracts

- [RPC protos](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/protos/dna_model_service.proto): service contract · Protobuf contracts defining the typed client-server boundary · `src/alphagenome/protos/dna_model_service.proto`
- [Tensor utils](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/tensor_utils.py): infrastructure · Tensor shaping, conversion, and validation helpers · `src/alphagenome/tensor_utils.py`
- [Typing](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/typing.py): infrastructure · Shared type aliases and validation-friendly typing support · `src/alphagenome/typing.py`
- [Colab utils](https://github.com/google-deepmind/alphagenome/blob/main/src/alphagenome/colab_utils.py): notebook support · Helpers for notebook workflows and interactive usage · `src/alphagenome/colab_utils.py`
- [GTF processing](https://github.com/google-deepmind/alphagenome/blob/main/scripts/process_gtf.py): script · Reference annotation preprocessing for GTF-style inputs · `scripts/process_gtf.py`

### Examples and docs

Notebooks and documentation that demonstrate package workflows

- [Colabs](https://github.com/google-deepmind/alphagenome/blob/main/colabs/quick_start.ipynb): examples · User workflows for quick start, variant scoring, visualization, and analysis · `colabs/quick_start.ipynb`
- [Docs](https://github.com/google-deepmind/alphagenome/blob/main/docs/source/index.md): documentation · Sphinx documentation covering installation, APIs, tutorials, and visualization guides · `docs/source/index.md`

### Other components

- **AlphaGenome SDK**: Python package · Client-side SDK for a hosted AlphaGenome inference service
- **AlphaGenome API**: external service · Hosted remote inference service accessed via authenticated RPC

## Connections

- AlphaGenome SDK → Genomic data: defines · Package exposes shared genomic domain objects
- AlphaGenome SDK → Client entry: provides · Main user entry point for remote access
- AlphaGenome SDK → ISM: includes · Interpretation utilities are part of the SDK
- AlphaGenome SDK → Plotting: includes · Visualization subsystem is shipped with the package
- AlphaGenome SDK → RPC protos: ships · Typed RPC contracts are part of the distribution
- AlphaGenome SDK → Colab utils: supports · Notebook workflow helpers are included
- Genomic data → Genome: contains · Genome and coordinate abstractions
- Genomic data → Transcripts: contains · Transcript objects and related metadata
- Genomic data → Gene annotations: contains · Gene annotation structures
- Genomic data → Ontology terms: contains · Ontology and tissue mapping terms
- Genomic data → Track data: contains · Track containers used as model inputs and outputs
- Genomic data → Junctions: contains · Splice junction data structures
- Genomic data → Fold intervals: contains · Interval split metadata for evaluation workflows
- Client entry → Model wrapper: creates · Authenticated client constructs model wrapper
- Model wrapper → RPC protos: calls · Prediction requests are marshaled through protobuf RPC contracts
- Model wrapper → AlphaGenome API: invokes · Remote hosted inference boundary
- Model wrapper → Model outputs: returns · Structured prediction outputs are wrapped locally
- Interval scoring → Model wrapper: uses · Interval scoring is built on the remote model wrapper
- Variant scoring → Model wrapper: uses · Variant scoring depends on remote prediction calls
- Variant scoring → Model outputs: compares · REF/ALT outputs are compared for variant effect analysis
- Track utilities → Track data: adapts · Maps track domain objects into model-facing structures
- Junction utilities → Junctions: adapts · Maps junction domain objects into scoring workflows
- ISM → Model outputs: analyzes · ISM operates on model outputs for attribution-style interpretation
- ISM → Variant scoring: builds on · Interpretation commonly follows variant scoring workflows
- Plotting → Plot components: composes · Figure assembly uses reusable drawing primitives
- Plotting → Transcript plots: specializes · Transcript-centric layouts extend the plotting layer
- Plotting → Model outputs: renders · Plots consume predictions and structured outputs
- Plotting → Genomic data: renders · Plots overlay genomic annotations and track objects
- Colab utils → Colabs: supports · Notebook workflows use package helpers
- GTF processing → Gene annotations: prepares · Script preprocesses reference gene annotation inputs
- Docs → Plotting: documents · Documentation covers visualization APIs and patterns
- Docs → Client entry: documents · Documentation covers installation and API usage
- Docs → ISM: documents · Docs explain interpretation workflows
- Colabs → Client entry: uses · Examples start from authenticated client usage
- Colabs → Variant scoring: uses · Examples demonstrate batch and single-variant scoring
- Colabs → Plotting: uses · Examples show visualization workflows
- Colabs → ISM: uses · Examples include downstream interpretation analysis
