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 tracks at
base-pair resolution. General section heatmaps do not trigger motif footprint
rendering.
Pinned Track Key Schema
pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:heatmap:HEATMAP_TILESET_SOURCE_ACTIVE_ISM_SCORES:<TilesetId>
<TrackMetadataName>: Exact track name from production metadata proto,
URL-encoded (%20 for spaces).
<StrandNumber>: 1 (STRAND_POSITIVE), 2 (STRAND_NEGATIVE), 3
(STRAND_UNSTRANDED).
<ScorerShortName>: RNA_SEQ, CHIP_TF, DNASE, ATAC, CAGE,
PROCAP, CHIP_HISTONE.
HEATMAP_TILESET_SOURCE_ACTIVE_ISM_SCORES: Required source identifier for
Active-ISM motif layers.
<TilesetId>: Server-assigned tileset identifier (17354278441953531756
for current production).
Recipe for Automatic Motif Display on Load
- Append
pinned:<PinnedKey> entries to lItems for the specific target
tracks only.
- Set viewport interval
i to base-pair resolution ($\le 1\text{ bp/px}$,
window $\le 380\text{ bp}$).
- 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.
1---
2name: alphagenome-atlas-website-links
3description: >-
4 Constructs deep-links and URLs for the AlphaGenome Atlas website. Supports generating single-variant exploration
5 links (1-based chr:pos:ref>alt), genomic locus views (1-based closed chr:start-end), candidate summary tables,
6 and AlphaGenome reference vs. alternate predictions. Use whenever visualizing, exploring, charting, or linking
7 genetic variants and genomic loci on the AlphaGenome Atlas, or when asked to inspect, view, or link predictions for a
8 genomic variant.
9metadata:
10 source: https://skillmd.com/skills/google-deepmind/alphagenome-atlas-website-links
11---
12
13# AlphaGenome Atlas Deep-Linking & URL Configuration
14
15Construct and validate deep-links for the AlphaGenome Atlas web application
16(`https://deepmind.google.com/science/alphagenome/atlas`).
17
18Base URL: `https://deepmind.google.com/science/alphagenome/atlas`
19
20> [!IMPORTANT] **Mandatory Atlas Deep-Linking with Variant Scores**: Whenever
21> presenting, discussing, or scoring genetic variants, you **MUST always provide
22> clickable deep-links to the
23> [AlphaGenome Atlas](https://deepmind.google.com/science/alphagenome/atlas)**.
24> Use `scripts/alphagenome_atlas_links.py` to automate link and table
25> generation.
26
27--------------------------------------------------------------------------------
28
29## Prerequisites
30
31```bash
32# 1. Single Variant Exploration Link:
33uv run scripts/alphagenome_atlas_links.py variant "chr9:128225994:G>A" \
34 --biosample K562 \
35 --modalities RNA_SEQ,DNASE,CHIP_TF
36
37# 2. Genomic Locus / Interval Link:
38uv run scripts/alphagenome_atlas_links.py locus "chr11:5288500-5290500" \
39 --biosample K562 \
40 --modalities RNA_SEQ,DNASE,CHIP_TF
41
42# 3. Format Candidate Variant Records Table (with embedded clickable links):
43uv run scripts/alphagenome_atlas_links.py table --input top_variants.json --biosample K562
44
45# 4. Construct Ref vs. Alt Track Predictions Link (/atlas/track-predictions):
46uv run scripts/alphagenome_atlas_links.py track-predictions \
47 --variant "chr15:42387805:C>G" \
48 --gene CAPN3 \
49 --biosample "Muscle_Skeletal"
50```
51
52--------------------------------------------------------------------------------
53
54## 2. URL Query Parameters
55
56* **`q`** (*string*, **Required**): Primary search target. Supports 1-based
57 closed intervals (`chr11:5288500-5290500`), gene symbols (`BRCA1`), Ensembl
58 IDs (`ENSG00000012048`), or 1-based variants (`chr7:27170000:A>G`).
59* **`m`** (*enum*, Optional): View mode. Defaults to `entity` for
60 genes/variants and `locus` for coordinate intervals. Use `variant` for
61 variant queries. (Allowed: `locus`, `entity`, `variant`, `motifs`).
62* **`i`** (*string*, Optional): Centered viewport zoom interval in 1-based
63 closed `chr:start-end` format (e.g. `chr11:5289310-5289690`). Required for
64 automatic motif rendering.
65* **`f`** (*string*, Optional): Comma-separated filter predicates in
66 `KEY:VALUE` format (e.g.
67 `BIOSAMPLE_NAME:K562,SCORER_MODALITY:RNA-seq,ASSAY_TRANSCRIPTOR_FACTOR:GATA1`).
68 Controls visible heatmap rows.
69* **`lItems`** (*string*, Optional): Layout item sequence, AVI score track
70 toggle (`avi`), section heatmaps, and pinned tracks list (e.g.
71 `avi,section:RNA_SEQ,section:DNASE,pinned:<TrackKey>`).
72* **`scores`** (*string*, Optional): Comma-separated list of `ScoreId` tokens
73 for the `/atlas/track-predictions` page comparison (e.g.
74 `<ScoreId1>,<ScoreId2>`).
75* **`md`** (*enum*, Optional): Active modality tab selector on the track
76 predictions view (`RNA_SEQ`, `SPLICE_JUNCTIONS`, `SPLICE_SITE_USAGE`,
77 `DNASE`).
78* **`tpRenames`** (*string*, Optional): Custom title overrides for specific
79 score predictions (`ScoreId:CustomTitle`).
80* **`tpLegendTitle`** (*string*, Optional): Custom legend title for the track
81 predictions chart card (e.g. `Predicted Gene Expression`).
82
83> [!IMPORTANT] **Variant Query Format**: Variants in `q` must strictly use
84> `chr:pos_1_based:ref>alt` format (e.g. `chr7:27170000:A>G` or URL-encoded
85> `chr7:27170000:A%3EG`, where the position is 1-based). **Do not use**
86> colon-separated alleles (`A:G`) or dbSNP rsIDs (rsIDs are unsupported).
87
88--------------------------------------------------------------------------------
89
90## 3. Multi-Modality Filtering & The Assay Group Gotcha (`f`)
91
92### Filter Groups & Boolean Evaluation
93
94Filters in `f` map to three primary evaluation groups:
95
96* **`Biosample` Group (`BIOSAMPLE_NAME`, `BIOSAMPLE_TYPE`)**: Evaluated with
97 **AND** logic.
98* **`Assay` Group (`SCORER_MODALITY`, `ASSAY_TRANSCRIPTOR_FACTOR`,
99 `ASSAY_HISTONE_MARK`)**: Evaluated with **OR** logic.
100* **`Gene` Group (`GENE_NAME`)**: Evaluated with **OR** logic.
101
102### ⚠️ Mandatory Multi-Modality Filter Rule
103
104`RNA-seq` and `DNase` tracks have no transcription factor code
105(`transcriptionFactorCode === ""`). If `f` contains *only*
106`ASSAY_TRANSCRIPTOR_FACTOR` filters under the Assay group, `RNA-seq` and `DNase`
107tracks fail the Assay evaluation and are hidden from the heatmap.
108
109To display `RNA-seq` and `DNase` tracks alongside specific ChIP-seq
110transcription factors, **explicitly include `SCORER_MODALITY:RNA-seq` and
111`SCORER_MODALITY:DNase`** in `f` (handled automatically by
112`scripts/alphagenome_atlas_links.py`):
113
114```
115f=BIOSAMPLE_NAME:<CellLine>,SCORER_MODALITY:RNA-seq,SCORER_MODALITY:DNase,ASSAY_TRANSCRIPTOR_FACTOR:<TF1>,ASSAY_TRANSCRIPTOR_FACTOR:<TF2>
116```
117
118--------------------------------------------------------------------------------
119
120## 4. Layout Configuration, AVI Scores, & Pinned Tracks (`lItems`)
121
122### Plotting AVI Scores and Modality Sections
123
124* **AVI Variant Impact Track (`avi`)**: Including `avi` in `lItems` renders
125 the top-level AlphaGenome Variant Impact score track for the interval or
126 variant.
127* **Database Modality Sections (`section:<MODALITY>`)**: Sections render full
128 unpinned heatmaps across all matching tracks for that modality (e.g.
129 `section:RNA_SEQ`, `section:DNASE`, `section:CHIP_TF`, `section:ATAC`,
130 `section:CAGE`).
131
132### Pinned Tracks & Motif Instances
133
134> [!NOTE] **Track-Specific Motif Guideline**: Pinned Active-ISM tracks with
135> motif instances and Contribution Weight Matrix (CWM) logos should **only be
136> added when specifically requested for individual tracks**. Only a limited
137> subset of tracks (such as key ChIP-TF or RNA-seq tracks relevant to the locus)
138> support and benefit from pinned motif overlays. For standard exploration
139> links, default section heatmaps
140> (`avi,section:RNA_SEQ,section:DNASE,section:CHIP_TF`) without pinned tracks
141> are preferred.
142
143Motif instances and CWM logos render **exclusively on pinned tracks** at
144base-pair resolution. General section heatmaps do not trigger motif footprint
145rendering.
146
147### Pinned Track Key Schema
148
149```
150pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:heatmap:HEATMAP_TILESET_SOURCE_ACTIVE_ISM_SCORES:<TilesetId>
151```
152
153* `<TrackMetadataName>`: Exact track name from production metadata proto,
154 URL-encoded (`%20` for spaces).
155* `<StrandNumber>`: `1` (`STRAND_POSITIVE`), `2` (`STRAND_NEGATIVE`), `3`
156 (`STRAND_UNSTRANDED`).
157* `<ScorerShortName>`: `RNA_SEQ`, `CHIP_TF`, `DNASE`, `ATAC`, `CAGE`,
158 `PROCAP`, `CHIP_HISTONE`.
159* `HEATMAP_TILESET_SOURCE_ACTIVE_ISM_SCORES`: Required source identifier for
160 Active-ISM motif layers.
161* `<TilesetId>`: Server-assigned tileset identifier (`17354278441953531756`
162 for current production).
163
164### Recipe for Automatic Motif Display on Load
165
1661. Append `pinned:<PinnedKey>` entries to `lItems` for the specific target
167 tracks only.
1682. Set viewport interval `i` to base-pair resolution ($\le 1\text{ bp/px}$,
169 window $\le 380\text{ bp}$).
1703. Configure `f` with cell line and transcription factors.
171
172--------------------------------------------------------------------------------
173
174## 5. Track Predictions & Ref vs. Alt Comparisons (`/atlas/track-predictions`)
175
176The dedicated `/atlas/track-predictions` page compares predicted functional
177profiles between the Reference and Alternate alleles for selected scores across
178genomic windows:
179
180* **Route**:
181 `https://deepmind.google.com/science/alphagenome/atlas/track-predictions`
182* **Visualizations**: Expanded line plots (expression, chromatin
183 accessibility, TF binding) and Sashimi arc charts (splice junctions).
184
185### Automated Prediction Link Generation (`scripts/alphagenome_atlas_links.py track-predictions`)
186
187Always construct track prediction URLs using `scripts/alphagenome_atlas_links.py
188track-predictions`. Manual `ScoreId` string formatting is error-prone due to
189donor/acceptor skipping coordinates, strand orientation (+/-), and genic vs.
190non-genic suffix rules. The script automatically handles coordinate extraction
191from GENCODE v46, track catalog resolution, and URL synthesis.
192
193```bash
194# Variant & Gene:
195uv run scripts/alphagenome_atlas_links.py track-predictions \
196 --variant "chr15:42387805:C>G" \
197 --gene CAPN3 \
198 --biosample "Muscle_Skeletal" \
199 --modalities SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF \
200 --tf CTCF
201
202# Interval/Locus query:
203uv run scripts/alphagenome_atlas_links.py track-predictions \
204 --variant "chr15:42387805:C>G" \
205 --interval "chr15:41869312-42917888" \
206 --biosample "Muscle_Skeletal" \
207 --modalities SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF
208```
209
210### Supported CLI Options for `track-predictions`
211
212* **`--variant`, `-v`** (*string*, default: `None`): Variant string in
213 `chr:pos_1_based:ref>alt` format.
214* **`--gene`, `-g`** (*string*, default: `None`): Target gene symbol (bounds
215 `i=` viewport and computes splice junctions).
216* **`--gene_id`** (*string*, default: `None`): Target Ensembl gene ID (e.g.
217 `ENSG00000092529.26`).
218* **`--interval`, `-i`** (*string*, default: `None`): Genomic interval
219 viewport in `chr:start-end` format.
220* **`--biosample`, `-b`** (*string*, default: `Muscle_Skeletal`): Target
221 biosample or tissue query (e.g. `Muscle_Skeletal`, `K562`, `Whole_Blood`).
222* **`--modalities`, `-m`** (*string*, default:
223 `SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF`): Comma-separated list of
224 modalities (`SPLICE_JUNCTIONS`, `RNA_SEQ`, `DNASE`, `ATAC`, `CHIP_TF`).
225* **`--tf`** (*string*, default: `CTCF`): Transcription factor name for
226 ChIP-TF tracks (e.g. `CTCF`, `GATA1`).
227* **`--rename`** (*string*, default: `None`): Custom track rename overrides in
228 the chart card.
229* **`--legend_title`** (*string*, default: `None`): Custom legend header for
230 the chart card.
231* **`--format`** (*enum*, default: `table`): Output format (`table`, `url`,
232 `json`).
233
234> [!IMPORTANT] **Mandatory Splicing & RNA-seq Co-Plotting Rule**: When
235> generating `/atlas/track-predictions` deep-links, plotting, or visualizing
236> variant impact data for splicing variants, **always plot continuous RNA-seq
237> expression alongside splicing tracks** (`SPLICE_JUNCTIONS`,
238> `SPLICE_SITE_USAGE`, `SPLICE_SITES`). Splicing mutations frequently activate
239> cryptic splice junctions and trigger nonsense-mediated decay (NMD) or alter
240> total transcript output; assessing splice junctions (sashimi arcs) together
241> with continuous RNA-seq read coverage is required to observe both the
242> structural splice defect and the resulting change in overall transcript
243> abundance.
244
245> [!IMPORTANT] **Always Provide Bounded `i=` in Track Prediction URLs**:
246> Omitting `scores=` or leaving the genomic interval (`i=`) unbounded causes the
247> web application to attempt querying all matching tracks across the broader
248> locus, leading to severe latency or page hanging. `alphagenome_atlas_links.py
249> track-predictions` automatically bounds `i=` to the target gene or requested
250> interval.