TellWorldAI World Archive
Ask中文

Home›Practice›Practice

Practice

Getting started with the AlphaGenome 2 API

Install the alphagenome client, set up an API key and run a first AlphaGenome 2 prediction and score for one human variant.

Who this is for

This guide is for researchers and students who want to call AlphaGenome 2 from Python for genomic prediction. By the end you should have the alphagenome package installed, an API key configured, and a working example that predicts and scores a variant's effect.

What AlphaGenome 2 is

AlphaGenome 2 is Google DeepMind's genomics model. It does not run on your machine. You call the hosted model through the lightweight alphagenome Python client, so no local GPU is needed[2]. The model takes a DNA sequence of up to 1 Mb together with a species and a condition, and predicts observed and imputed coverage tracks, gene expression, splicing and contact maps[3].

The condition is the central idea. Each call predicts for one condition: a reference tissue or cell type passed as condition=, where composite conditions such as UBERON:0000178_CL:0001054 are allowed, or your own single-cell data passed as cell_conditioning= with up to 256 cells[1]. To compare conditions, loop over them, or use batch arguments such as conditions=[1].

AlphaGenome Atlas is a separate route. It offers pre-computed effects for human variants without running the model, through a zero-code website or an Atlas API[1]. To reproduce results from the AlphaGenome paper, score variants across all tissues and cell types at once, or predict PRO-cap, use AlphaGenome 1 instead[1].

What you need

  • A system: Linux, macOS or Windows. No local GPU is required[2].
  • An account: apply for a free AlphaGenome API key. Both model predictions and Atlas queries need it[2].
  • A Python environment: a virtual environment keeps the dependencies separate from the rest of your system.

Install the alphagenome package

The most direct route is pip. Create and activate a virtual environment, then install the latest PyPI release[2]:

python3 -m venv .venv
source .venv/bin/activate
pip install alphagenome

With uv, run uv venv, then uv pip install alphagenome. In an existing uv project, uv add alphagenome adds the package directly. With conda, run conda create -n alphagenome python -y and conda activate alphagenome, then install with pip. If you want to work from source, clone the GitHub repository and run pip install -e . inside it. After upstream changes, run git pull and then pip install -e . again[2].

In Google Colab, the first cell of every notebook installs the package with ! pip install alphagenome. To keep the key out of your code, store it in the Secrets panel under the name ALPHA_GENOME_API_KEY and turn on Notebook access[2].

Configure the API key

When you run scripts or Jupyter notebooks locally, export the key as an environment variable. The line below can also go into ~/.zshrc or ~/.bashrc[2]:

export ALPHA_GENOME_API_KEY="YOUR_API_KEY"

colab_utils.get_api_key() reads this variable first and falls back to Colab Secrets, so the same code runs locally and in Colab[2].

To check the installation and the key, run the script below. It prints the number of supported human conditions[2]:

from alphagenome import colab_utils
from alphagenome.models.v2 import dna_client

dna_model = dna_client.create(colab_utils.get_api_key())
print(len(dna_model.supported_conditions()), 'supported human conditions')

A first example: a variant's effect on GLB1L expression

The official example uses CD14-positive monocytes in blood (UBERON:0000178_CL:0001054). The variant sits on chr2 at position 219243701, with reference base C and alternate base T, and the gene of interest is GLB1L[1]. The workflow has four steps: choose a condition, select a region, predict or score, and plot.

  1. Choose a condition with condition = 'UBERON:0000178_CL:0001054'.
  2. Select a region. variant.reference_interval.resize(dna_client.SEQUENCE_LENGTH_1MB) builds a 1 Mb interval centred on the variant[1].
  3. Predict and score. predict_variant with requested_outputs=[dna_client.OutputType.RNA_SEQ] returns RNA-seq tracks for the reference (REF) and alternate (ALT) sequences. score_variant applies the recommended RNA-seq scorer across the interval, and tidy_scores filters the table to GLB1L[1].
  4. Plot. plot_components.OverlaidTracks overlays REF and ALT on the negative strand, because GLB1L lies there[1].

Replace YOUR_API_KEY with your own key to run the full example[1]:

from alphagenome.data import genome
from alphagenome.models.v2 import dna_client
from alphagenome.models.v2 import variant_scorers
from alphagenome.visualization import plot_components

dna_model = dna_client.create('YOUR_API_KEY')

# 1. Choose a condition: CD14-positive monocytes in blood.
condition = 'UBERON:0000178_CL:0001054'

# 2. Select a genomic region: center a 1 Mb interval on the variant.
variant = genome.Variant(
    chromosome='chr2',
    position=219243701,
    reference_bases='C',
    alternate_bases='T',
)
interval = variant.reference_interval.resize(dna_client.SEQUENCE_LENGTH_1MB)

Using your own single-cell data

If you have human single-cell RNA-seq data, expression conditioning can replace a reference condition. The input is an AnnData object of raw integer UMI counts with Ensembl gene IDs in var_names. Each call accepts up to 256 cells, and the cell_condition_name label is written into the output metadata[1]. The output type becomes SC_GENE_EXPRESSION_DENOISED, which is denoised single-cell gene expression with one channel per strand in CPM[1][3]. Scoring uses RECOMMENDED_VARIANT_SCORERS['SC_GENE_EXPRESSION_DENOISED'], and plotting uses OverlaidGeneExpression, which can use a log scale[1].

How AlphaGenome 2 differs from AlphaGenome 1

Both versions come from the same package: alphagenome.models.v2 for AlphaGenome 2 and alphagenome.models.v1 for AlphaGenome 1[3]. The main differences are:

  • New output types: SC_GENE_EXPRESSION_DENOISED, SC_GENE_EXPRESSION, SC_ATAC, METHYLATION and CELL_EMBEDDINGS[3].
  • PROCAP has been removed; use CAGE for transcription start site activity[3].
  • SPLICE_SITES is now condition-specific, with 5 channels per condition: donor +, acceptor +, donor -, acceptor - and padding .[3].
  • Variant scores have only a raw_score column, with no quantile_score[3].
  • Metadata lookups differ: AlphaGenome 1 uses output_metadata(), while AlphaGenome 2 uses supported_conditions(), which has one row per condition, and observed_metadata() for the measured tracks[3].
  • Each track is labelled in .metadata['imputation_mode'] as observed, imputed_supported or imputed_exploratory, which separates measured values from imputed ones[3].

Limits and common questions

  • Each call takes one condition. To compare several tissues or cell types, loop over them or use the batch arguments[1].
  • With expression conditioning, a call accepts up to 256 cells[1].
  • The input sequence can be up to 1 Mb[3].
  • Code that still reads quantile_score must change when you move to AlphaGenome 2, because that column is no longer produced[3].
  • If your analysis used PROCAP, switch to CAGE for transcription start site activity[3].

Next steps

The official tutorials begin with choosing a condition and later cover conditioning on your own single-cell data. For end-to-end biological analyses, see the Vignettes. The user guide explains data objects, metadata and variant scoring[1].

Adapted from the AlphaGenome documentation by Google DeepMind[1], released under the CC-BY-4.0 license.

Sources

  1. 1
    Getting startedGoogle DeepMind AlphaGenome docs
  2. 2
    InstallationGoogle DeepMind AlphaGenome docs
  3. 3
    Migrating from AlphaGenome 1Google DeepMind AlphaGenome docs

Cite this page: Getting started with the AlphaGenome 2 API. TellWorld, https://www.tellworld.net/practice/practice-alphagenome-2-quickstart. Updated 2026-11-15

Related news

View all