How google-deepmind/alphagenome works
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: __init__.py Genomic data · plot.py Plotting · dna_model.py Model wrapper · quick_start.ipynb Colabs
Components 28
Data domain
Shared genomic entities and reference annotations
- Genomic data · Shared genomic vocabulary for intervals, variants, transcripts, genes, ontology, junctions, and tracks
src/alphagenome/data/__init__.py - Genome · Genome coordinate and reference sequence abstractions
src/alphagenome/data/genome.py - Transcripts · Transcript-centric annotations and structures
src/alphagenome/data/transcript.py - Gene annotations · Gene-level annotation structures and derived metadata
src/alphagenome/data/gene_annotation.py - Ontology terms · Tissue or functional ontology mapping objects
src/alphagenome/data/ontology.py - Track data · Per-position or per-interval track containers used across scoring and plotting
src/alphagenome/data/track_data.py - Junctions · Splice junction and junction-like data structures
src/alphagenome/data/junction_data.py - Fold intervals · 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 · User-facing entry point for creating authenticated service clients
src/alphagenome/models/dna_client.py - Model wrapper · High-level wrapper around remote AlphaGenome prediction calls
src/alphagenome/models/dna_model.py - Model outputs · Structured containers for returned predictions and selected outputs
src/alphagenome/models/dna_output.py - Interval scoring · Whole-interval scoring and post-processing over remote predictions
src/alphagenome/models/interval_scorers.py - Variant scoring · REF/ALT comparison and variant-effect scoring workflows
src/alphagenome/models/variant_scorers.py - Track utilities · Helpers that map track data to model input/output structures
src/alphagenome/models/track_data_utils.py - Junction utilities · Helpers that map junction data into scoring and model workflows
src/alphagenome/models/junction_data_utils.py
Interpretation
Post-processing and attribution utilities
- ISM · In silico mutagenesis for attribution-style variant analysis
src/alphagenome/interpretation/ism.py
Visualization
Plotting and figure composition
- Plotting · Top-level figure assembly for model outputs and annotations
src/alphagenome/visualization/plot.py - Plot components · Composable primitives for tracks, markers, and overlays
src/alphagenome/visualization/plot_components.py - Transcript plots · Transcript-centric plotting helpers and specialized layouts
src/alphagenome/visualization/plot_transcripts.py
Support
Shared utilities, scripts, and service contracts
- RPC protos · Protobuf contracts defining the typed client-server boundary
src/alphagenome/protos/dna_model_service.proto - Tensor utils · Tensor shaping, conversion, and validation helpers
src/alphagenome/tensor_utils.py - Typing · Shared type aliases and validation-friendly typing support
src/alphagenome/typing.py - Colab utils · Helpers for notebook workflows and interactive usage
src/alphagenome/colab_utils.py - GTF processing · Reference annotation preprocessing for GTF-style inputs
scripts/process_gtf.py
Examples and docs
Notebooks and documentation that demonstrate package workflows
Other components
- AlphaGenome SDK · Client-side SDK for a hosted AlphaGenome inference service
- AlphaGenome API · Hosted remote inference service accessed via authenticated RPC
Connections 37
- 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