AlphaGenome Atlas Deep-Linking & URL-Konfiguration

Was macht AlphaGenome Atlas Deep-Linking & URL-Konfiguration?

Erstelle und validiere Deep-Links für die AlphaGenome Atlas-Webanwendung (https://deepmind.google.com/science/alphagenome/atlas).

Basis-URL: https://deepmind.google.com/science/alphagenome/atlas

[!IMPORTANT] Verbindliche Atlas-Deep-Links mit Variantenbewertungen: Wann immer genetische Varianten präsentiert, diskutiert oder bewertet werden, MÜSSEN Sie immer klickbare Deep-Links zum AlphaGenome Atlas bereitstellen. Verwenden Sie scripts/alphagenome_atlas_links.py, um die Link- und Tabellenerstellung zu automatisieren.

---

Voraussetzungen

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

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

# 3. Kandidatenvarianten-Datensatztabelle formatieren (mit eingebetteten klickbaren Links):
uv run scripts/alphagenome_atlas_links.py table --input top_variants.json --biosample K562

# 4. Referenz- vs. Alternativ-Track-Vorhersage-Link (/atlas/track-predictions) erstellen:
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --gene CAPN3 \
  --biosample "Muscle_Skeletal"

---

2. URL-Abfrageparameter

• q (string, Erforderlich): Primäres Suchziel. Unterstützt 1-basierte geschlossene Intervalle (chr11:5288500-5290500), Gensymbole (BRCA1), Ensembl- IDs (ENSG00000012048) oder 1-basierte Varianten (chr7:27170000:A>G).
• m (enum, Optional): Ansichtsmodus. Standard ist entity für Gene/Varianten und locus für Koordinatenintervalle. Verwenden Sie variant für Variantenabfragen. (Erlaubt: locus, entity, variant, motifs).
• i (string, Optional): Zentriertes Viewport-Zoomintervall im 1-basierten geschlossenen chr:start-end-Format (z. B. chr11:5289310-5289690). Erforderlich für die automatische Motivdarstellung.
• f (string, Optional): Kommagetrennte Filterprädikate im KEY:VALUE-Format (z. B. BIOSAMPLE_NAME:K562,SCORER_MODALITY:RNA-seq,ASSAY_TRANSCRIPTOR_FACTOR:GATA1). Steuert sichtbare Heatmap-Zeilen.
• lItems (string, Optional): Layout-Elementsequenz, AVI-Bewertungs-Track-Umschalter (avi), Abschnitts-Heatmaps und angeheftete Track-Liste (z. B. avi,section:RNA_SEQ,section:DNASE,pinned:<TrackKey>).
• scores (string, Optional): Kommagetrennte Liste von ScoreId-Tokens für den Vergleich auf der Seite /atlas/track-predictions (z. B. <ScoreId1>,<ScoreId2>).
• md (enum, Optional): Aktiver Modalitäten-Tab-Selektor auf der Trackvorhersage- ansicht (RNA_SEQ, SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, DNASE).
• tpRenames (string, Optional): Benutzerdefinierte Titelüberschreibungen für bestimmte Bewertungsvorhersagen (ScoreId:CustomTitle).
• tpLegendTitle (string, Optional): Benutzerdefinierter Legendentitel für die Trackvorhersage- Diagrammkarte (z. B. Predicted Gene Expression).

[!IMPORTANT] Variantenabfrageformat: Varianten in q müssen strikt das Format chr:pos_1_based:ref>alt verwenden (z. B. chr7:27170000:A>G oder URL-kodiert chr7:27170000:A%3EG, wobei die Position 1-basiert ist). Verwenden Sie nicht doppelpunktgetrennte Allele (A:G) oder dbSNP-rsIDs (rsIDs werden nicht unterstützt).

---

3. Multi-Modalitätsfilterung & Der Assay-Gruppen-Haken (f)

Filtergruppen & Boolesche Auswertung

Filter in f werden drei primären Auswertungsgruppen zugeordnet:

• Biosample-Gruppe (BIOSAMPLE_NAME, BIOSAMPLE_TYPE): Wird mit UND-Logik ausgewertet.
• Assay-Gruppe (SCORER_MODALITY, ASSAY_TRANSCRIPTOR_FACTOR, ASSAY_HISTONE_MARK): Wird mit ODER-Logik ausgewertet.
• Gene-Gruppe (GENE_NAME): Wird mit ODER-Logik ausgewertet.

⚠️ Verbindliche Multi-Modalitätsfilter-Regel

RNA-seq- und DNase-Tracks haben keinen Transkriptionsfaktor-Code (transcriptionFactorCode === ""). Wenn f unter der Assay-Gruppe nur ASSAY_TRANSCRIPTOR_FACTOR-Filter enthält, bestehen RNA-seq- und DNase-Tracks die Assay-Auswertung nicht und werden in der Heatmap ausgeblendet.

Um RNA-seq- und DNase-Tracks zusammen mit bestimmten ChIP-seq-Transkriptionsfaktoren anzuzeigen, müssen SCORER_MODALITY:RNA-seq und SCORER_MODALITY:DNase explizit in f aufgenommen werden (wird automatisch von scripts/alphagenome_atlas_links.py übernommen):

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

---

4. Layout-Konfiguration, AVI-Bewertungen & Angeheftete Tracks (lItems)

Darstellung von AVI-Bewertungen und Modalitätenabschnitten

• AVI-Varianten-Impact-Track (avi): Die Aufnahme von avi in lItems rendert den übergeordneten AlphaGenome-Variant-Impact-Bewertungstrack für das Intervall oder die Variante.
• Datenbank-Modalitätenabschnitte (section:<MODALITY>): Abschnitte rendern vollständige nicht angeheftete Heatmaps über alle passenden Tracks für diese Modalität (z. B. section:RNA_SEQ, section:DNASE, section:CHIP_TF, section:ATAC, section:CAGE).

Angeheftete Tracks & Motivinstanzen

[!NOTE] Track-spezifische Motiv-Richtlinie: Angeheftete Active-ISM-Tracks mit Motivinstanzen und Contribution-Weight-Matrix (CWM)-Logos sollten nur dann hinzugefügt werden, wenn speziell für einzelne Tracks angefordert. Nur eine begrenzte Untermenge von Tracks (wie relevante ChIP-TF- oder RNA-seq-Tracks für den Lokus) unterstützt und profitiert von angehefteten Motiv-Overlays. Für Standard-Explorationslinks werden Standard-Abschnitts-Heatmaps (avi,section:RNA_SEQ,section:DNASE,section:CHIP_TF) ohne angeheftete Tracks bevorzugt.

Motivinstanzen und CWM-Logos werden ausschließlich auf angehefteten Sequenztracks (ACTIVE_ISM oder RAW_SCORES, nicht REF_SCORES) mit Basenpaar-Auflösung gerendert. Allgemeine Abschnitts-Heatmaps lösen keine Motiv-Footprint-Darstellung aus.

Schema des angehefteten Track-Keys

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

Beispiel für einen lItems-Eintrag in einer rohen URL-Abfragezeichenfolge:

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

• <TrackMetadataName>: Exakter Track-Name aus dem Metadaten-Protokoll (z. B. EFO:0002067 TF ChIP-seq GATA1), prozentkodiert (%20 für Leerzeichen) in rohen URL-Abfragezeichenfolgen (oder unkodiert, wenn über urllib.parse.urlencode übergeben).
• <StrandNumber>: 1 (STRAND_POSITIVE), 2 (STRAND_NEGATIVE), 3 (STRAND_UNSTRANDED).
• <ScorerShortName>: RNA_SEQ, CHIP_TF, DNASE, ATAC, CAGE, PROCAP, CHIP_HISTONE (oder RAW_SCORES-nur Modalitäten: SPLICE_SITES, SPLICE_SITE_USAGE, SPLICE_JUNCTIONS, POLYADENYLATION, CONTACT_MAPS).
• <Source>: Heatmap-Kachelsatz-Quellenkennung: ACTIVE_ISM (aktivitätsgewichtete _TIMES_ACTIVE Motiv-Footprints und CWM-Sequenzlogos), RAW_SCORES (rohe ISM-Varianten-Bewertungstracks, rendern auch rohe ISM-Motiv- Footprints und CWM-Sequenzlogos über alle Modalitäten) oder REF_SCORES (kontinuierliche Referenzsignalliniendiagramme ohne Sequenzbuchstaben oder -Motive). Kalibrierte und AVI-Tracks können nicht angeheftet werden, und Legacy- :heatmap:...:<TilesetId>-Suffixe schlagen bei der Track-Suche fehl und werden ignoriert.

Rezept für automatische Motiv-Anzeige beim Laden

1. Fügen Sie Einträge der Form pinned:<TrackMetadataName>:<StrandNumber>:<ScorerShortName>:<Source> (mit ACTIVE_ISM für aktivitätsgewichtete Motive oder RAW_SCORES für rohe ISM- Motive) direkt an lItems für die spezifischen Ziel-Tracks an.
2. Setzen Sie das Viewport-Intervall i auf Basenpaar-Auflösung ($\ge 2\text{ px/bp}$, Fenster $\le 380\text{ bp}$).
3. Konfigurieren Sie f mit Zelllinie und Transkriptionsfaktoren.

---

5. Trackvorhersagen & Referenz-gegen-Alternativ-Vergleiche (/atlas/track-predictions)

Die spezielle Seite /atlas/track-predictions vergleicht vorhergesagte funktionelle Profile zwischen dem Referenz- und dem Alternativ-Allel für ausgewählte Bewertungen über genomische Fenster hinweg:

• Route: https://deepmind.google.com/science/alphagenome/atlas/track-predictions
• Visualisierungen: Erweiterte Liniendiagramme (Expression, Chromatin- zugänglichkeit, TF-Bindung) und Sashimi-Bogendiagramme (Spleißstellen).

Automatisierte Vorhersagelink-Generierung (scripts/alphagenome_atlas_links.py track-predictions)

Erstellen Sie Trackvorhersage-URLs immer mit scripts/alphagenome_atlas_links.py track-predictions. Manuelles ScoreId-String-Formatieren ist fehleranfällig aufgrund von Donor/Akzeptor-Skipping-Koordinaten, Strangorientierung (+/-) und genischen vs. nichttgenischen Suffix-Regeln. Das Skript übernimmt automatisch die Koordinatenextraktion aus GENCODE v46, die Trackkatalogauflösung und die URL-Synthese.

# Variante & Gen:
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

# Intervall/Lokus-Abfrage:
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

Unterstützte CLI-Optionen für track-predictions

• --variant, -v (string, Standard: None): Variantenstring im Format chr:pos_1_based:ref>alt.
• --gene, -g (string, Standard: None): Ziel-Gensymbol (begrenzt i=-Viewport und berechnet Spleißstellen).
• --gene_id (string, Standard: None): Ziel-Ensembl-Gen-ID (z. B. ENSG00000092529.26).
• --interval, -i (string, Standard: None): Genomisches Intervall-Viewport im Format chr:start-end.
• --biosample, -b (string, Standard: Muscle_Skeletal): Ziel- Bioprobe oder Gewebeabfrage (z. B. Muscle_Skeletal, K562, Whole_Blood).
• --modalities, -m (string, Standard: SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF): Kommagetrennte Liste von Modalitäten (SPLICE_JUNCTIONS, RNA_SEQ, DNASE, ATAC, CHIP_TF).
• --tf (string, Standard: CTCF): Transkriptionsfaktor-Name für ChIP-TF-Tracks (z. B. CTCF, GATA1).
• --rename (string, Standard: None): Benutzerdefinierte Track-Umbenennungs- überschreibungen in der Diagrammkarte.
• --legend_title (string, Standard: None): Benutzerdefinierter Legendenkopf für die Diagrammkarte.
• --format (enum, Standard: table): Ausgabeformat (table, url, json).

[!IMPORTANT] Verbindliche Spleiß- & RNA-seq-Koplotting-Regel: Bei der Generierung von Deep-Links zu /atlas/track-predictions, der Darstellung oder Visualisierung von Varianten-Impact-Daten für Spleißvarianten immer RNA-seq-Expression zusammen mit Spleiß-Tracks darstellen (SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, SPLICE_SITES). Spleißmutationen aktivieren häufig kryptische Spleißstellen und lösen Nonsense-vermittelten Abbau (NMD) aus oder verändern die gesamte Transkriptausgabe; Die Bewertung von Spleißstellen (Sashimi-Bögen) zusammen mit der kontinuierlichen RNA-seq-Read-Abdeckung ist erforderlich, um sowohl den strukturellen Spleißdefekt als auch die daraus resultierende Änderung der Gesamt-Transkripthäufigkeit zu beobachten.

[!IMPORTANT] Immer begrenztes i= in Trackvorhersage-URLs angeben: Das Weglassen von scores= oder das Belassen des genomischen Intervalls (i=) ohne Begrenzung führt dazu, dass die Webanwendung versucht, alle passenden Tracks über den gesamten Lokus abzufragen, was zu erheblicher Latenz oder Seitenhängen führt. alphagenome_atlas_links.py track-predictions begrenzt i= automatisch auf das Zielgen oder das angeforderte Intervall.