alphagenome-atlas-website-links — Claude Code skill: Atlas deep-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 VCF-style coordinates),
  genomic locus views (1-based closed chr:start-end), candidate summary tables,
  and AlphaGenome reference vs. alternate predictions. Use when 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. Don't use for computing raw AlphaGenome variant predictions
  directly without Atlas URLs (use alphagenome-single-variant-analysis or
  alphagenome-variant-impact-score).
---

# 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

```bash
# 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.

```bash
# 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.