AlphaGenome Atlas Deep-Linking & URL Configuration

Construct and validate deep-links for the AlphaGenome Atlas web application (https://deepmind.google.com/science/alphagenome/atlas).

Base URL: https://deepmind.google.com/science/alphagenome/atlas

[!IMPORTANT] Mandatory Atlas Deep-Linking with Variant Scores: Whenever presenting, discussing, or scoring genetic variants, you MUST always provide clickable deep-links to the AlphaGenome Atlas. Use scripts/alphagenome_atlas_links.py to automate link and table generation.

---

Prerequisites

# 1. Single Variant Exploration Link:
uv run scripts/alphagenome_atlas_links.py variant "chr9:128225994:G>A" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 2. Genomic Locus / Interval Link:
uv run scripts/alphagenome_atlas_links.py locus "chr11:5288500-5290500" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 3. Format Candidate Variant Records Table (with embedded clickable links):
uv run scripts/alphagenome_atlas_links.py table --input top_variants.json --biosample K562

# 4. Construct Ref vs. Alt Track Predictions Link (/atlas/track-predictions):
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --gene CAPN3 \
  --biosample "Muscle_Skeletal"

---

2. URL Query Parameters

• q (string, Required): Primary search target. Supports 1-based closed intervals (chr11:5288500-5290500), gene symbols (BRCA1), Ensembl IDs (ENSG00000012048), or 1-based variants (chr7:27170000:A>G).
• m (enum, Optional): View mode. Defaults to entity for genes/variants and locus for coordinate intervals. Use variant for variant queries. (Allowed: locus, entity, variant, motifs).
• i (string, Optional): Centered viewport zoom interval in 1-based closed chr:start-end format (e.g. chr11:5289310-5289690). Required for automatic motif rendering.
• f (string, Optional): Comma-separated filter predicates in KEY:VALUE format (e.g. BIOSAMPLE_NAME:K562,SCORER_MODALITY:RNA-seq,ASSAY_TRANSCRIPTOR_FACTOR:GATA1). Controls visible heatmap rows.
• lItems (string, Optional): Layout item sequence, AVI score track toggle (avi), section heatmaps, and pinned tracks list (e.g. avi,section:RNA_SEQ,section:DNASE,pinned:<TrackKey>).
• scores (string, Optional): Comma-separated list of ScoreId tokens for the /atlas/track-predictions page comparison (e.g. <ScoreId1>,<ScoreId2>).
• md (enum, Optional): Active modality tab selector on the track predictions view (RNA_SEQ, SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, DNASE).
• tpRenames (string, Optional): Custom title overrides for specific score predictions (ScoreId:CustomTitle).
• tpLegendTitle (string, Optional): Custom legend title for the track predictions chart card (e.g. Predicted Gene Expression).

[!IMPORTANT] Variant Query Format: Variants in q must strictly use chr:pos_1_based:ref>alt format (e.g. chr7:27170000:A>G or URL-encoded chr7:27170000:A%3EG, where the position is 1-based). Do not use colon-separated alleles (A:G) or dbSNP rsIDs (rsIDs are unsupported).

---

3. Multi-Modality Filtering & The Assay Group Gotcha (f)

Filter Groups & Boolean Evaluation

Filters in f map to three primary evaluation groups:

• Biosample Group (BIOSAMPLE_NAME, BIOSAMPLE_TYPE): Evaluated with AND logic.
• Assay Group (SCORER_MODALITY, ASSAY_TRANSCRIPTOR_FACTOR, ASSAY_HISTONE_MARK): Evaluated with OR logic.
• Gene Group (GENE_NAME): Evaluated with OR logic.

⚠️ Mandatory Multi-Modality Filter Rule

RNA-seq and DNase tracks have no transcription factor code (transcriptionFactorCode === ""). If f contains only ASSAY_TRANSCRIPTOR_FACTOR filters under the Assay group, RNA-seq and DNase tracks fail the Assay evaluation and are hidden from the heatmap.

To display RNA-seq and DNase tracks alongside specific ChIP-seq transcription factors, explicitly include SCORER_MODALITY:RNA-seq and SCORER_MODALITY:DNase in f (handled automatically by scripts/alphagenome_atlas_links.py):

f=BIOSAMPLE_NAME:<CellLine>,SCORER_MODALITY:RNA-seq,SCORER_MODALITY:DNase,ASSAY_TRANSCRIPTOR_FACTOR:<TF1>,ASSAY_TRANSCRIPTOR_FACTOR:<TF2>

---

4. Layout Configuration, AVI Scores, & Pinned Tracks (lItems)

Plotting AVI Scores and Modality Sections

• AVI Variant Impact Track (avi): Including avi in lItems renders the top-level AlphaGenome Variant Impact score track for the interval or variant.
• Database Modality Sections (section:<MODALITY>): Sections render full unpinned heatmaps across all matching tracks for that modality (e.g. section:RNA_SEQ, section:DNASE, section:CHIP_TF, section:ATAC, section:CAGE).

Pinned Tracks & Motif Instances

[!NOTE] Track-Specific Motif Guideline: Pinned Active-ISM tracks with motif instances and Contribution Weight Matrix (CWM) logos should only be added when specifically requested for individual tracks. Only a limited subset of tracks (such as key ChIP-TF or RNA-seq tracks relevant to the locus) support and benefit from pinned motif overlays. For standard exploration links, default section heatmaps (avi,section:RNA_SEQ,section:DNASE,section:CHIP_TF) without pinned tracks are preferred.

Motif instances and CWM logos render exclusively on pinned sequence tracks (ACTIVE_ISM or RAW_SCORES, not REF_SCORES) at base-pair resolution. General section heatmaps do not trigger motif footprint rendering.

Pinned Track Key Schema

pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:<Source>

Example lItems entry in a raw URL query string:

pinned:EFO:0002067%20TF%20ChIP-seq%20GATA1:3:CHIP_TF:ACTIVE_ISM

• <TrackMetadataName>: Exact track name from metadata proto (e.g. EFO:0002067 TF ChIP-seq GATA1), percent-encoded (%20 for spaces) in raw URL query strings (or unencoded when passed through urllib.parse.urlencode).
• <StrandNumber>: 1 (STRAND_POSITIVE), 2 (STRAND_NEGATIVE), 3 (STRAND_UNSTRANDED).
• <ScorerShortName>: RNA_SEQ, CHIP_TF, DNASE, ATAC, CAGE, PROCAP, CHIP_HISTONE (or RAW_SCORES-only modalities: SPLICE_SITES, SPLICE_SITE_USAGE, SPLICE_JUNCTIONS, POLYADENYLATION, CONTACT_MAPS).
• <Source>: Heatmap tileset source identifier: ACTIVE_ISM (activity-weighted _TIMES_ACTIVE motif footprints and CWM sequence logos), RAW_SCORES (raw ISM variant-score tracks, also rendering raw ISM motif footprints and CWM sequence logos across all modalities), or REF_SCORES (continuous reference signal line charts without sequence letters or motifs). Calibrated and AVI tracks cannot be pinned, and legacy :heatmap:...:<TilesetId> suffixes fail track lookup and are ignored.

Recipe for Automatic Motif Display on Load

1. Append entries of the form pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:<Source> (using ACTIVE_ISM for activity-weighted motifs or RAW_SCORES for raw ISM motifs) directly to lItems for the specific target tracks only.
2. Set viewport interval i to base-pair resolution ($\ge 2\text{ px/bp}$, window $\le 380\text{ bp}$).
3. Configure f with cell line and transcription factors.

---

5. Track Predictions & Ref vs. Alt Comparisons (/atlas/track-predictions)

The dedicated /atlas/track-predictions page compares predicted functional profiles between the Reference and Alternate alleles for selected scores across genomic windows:

• Route: https://deepmind.google.com/science/alphagenome/atlas/track-predictions
• Visualizations: Expanded line plots (expression, chromatin accessibility, TF binding) and Sashimi arc charts (splice junctions).

Automated Prediction Link Generation (scripts/alphagenome_atlas_links.py track-predictions)

Always construct track prediction URLs using scripts/alphagenome_atlas_links.py track-predictions. Manual ScoreId string formatting is error-prone due to donor/acceptor skipping coordinates, strand orientation (+/-), and genic vs. non-genic suffix rules. The script automatically handles coordinate extraction from GENCODE v46, track catalog resolution, and URL synthesis.

# Variant & Gene:
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --gene CAPN3 \
  --biosample "Muscle_Skeletal" \
  --modalities SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF \
  --tf CTCF

# Interval/Locus query:
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --interval "chr15:41869312-42917888" \
  --biosample "Muscle_Skeletal" \
  --modalities SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF

Supported CLI Options for track-predictions

• --variant, -v (string, default: None): Variant string in chr:pos_1_based:ref>alt format.
• --gene, -g (string, default: None): Target gene symbol (bounds i= viewport and computes splice junctions).
• --gene_id (string, default: None): Target Ensembl gene ID (e.g. ENSG00000092529.26).
• --interval, -i (string, default: None): Genomic interval viewport in chr:start-end format.
• --biosample, -b (string, default: Muscle_Skeletal): Target biosample or tissue query (e.g. Muscle_Skeletal, K562, Whole_Blood).
• --modalities, -m (string, default: SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF): Comma-separated list of modalities (SPLICE_JUNCTIONS, RNA_SEQ, DNASE, ATAC, CHIP_TF).
• --tf (string, default: CTCF): Transcription factor name for ChIP-TF tracks (e.g. CTCF, GATA1).
• --rename (string, default: None): Custom track rename overrides in the chart card.
• --legend_title (string, default: None): Custom legend header for the chart card.
• --format (enum, default: table): Output format (table, url, json).

[!IMPORTANT] Mandatory Splicing & RNA-seq Co-Plotting Rule: When generating /atlas/track-predictions deep-links, plotting, or visualizing variant impact data for splicing variants, always plot continuous RNA-seq expression alongside splicing tracks (SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, SPLICE_SITES). Splicing mutations frequently activate cryptic splice junctions and trigger nonsense-mediated decay (NMD) or alter total transcript output; assessing splice junctions (sashimi arcs) together with continuous RNA-seq read coverage is required to observe both the structural splice defect and the resulting change in overall transcript abundance.

[!IMPORTANT] Always Provide Bounded i= in Track Prediction URLs: Omitting scores= or leaving the genomic interval (i=) unbounded causes the web application to attempt querying all matching tracks across the broader locus, leading to severe latency or page hanging. alphagenome_atlas_links.py track-predictions automatically bounds i= to the target gene or requested interval.