/alphagenome_atlas_website_links

name: alphagenome-atlas-website-links
description: >-
  Constructs deep-links and URLs for the AlphaGenome Atlas website. Supports generating single-variant exploration
  links (1-based chr:pos:ref>alt), genomic locus views (1-based closed chr:start-end), candidate summary tables,
  and AlphaGenome reference vs. alternate predictions. Use whenever visualizing, exploring, charting, or linking
  genetic variants and genomic loci on the AlphaGenome Atlas, or when asked to inspect, view, or link predictions for a
  genomic variant.

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](https://deepmind.google.com/science/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**: Pi