google-deepmind/science-skills

Variantenanalyse mit AlphaGenome

Voraussetzungen

1. uv: Lies die uv-Skill und befolge deren Setup-Anweisungen, um sicherzustellen, dass uv installiert und im PATH ist.

2. Benutzerbenachrichtigung: Falls .licenses/alphagenome_single_variant_analysis_LICENSE.txt noch nicht im Arbeitsverzeichnis existiert, (1) benachrichtige den Benutzer deutlich, dass er die Bedingungen unter https://deepmind.google.com/science/alphagenome/ prüfen soll, und (2) erstelle die Datei mit dem Benachrichtigungstext und Zeitstempel.

3. .env-Datei: Stelle sicher, dass die .env-Datei in deinem Home-Verzeichnis existiert. Erstelle eine, falls sie nicht existiert.

4. ALPHAGENOME_API_KEY: Diese Skill benötigt einen API-Schlüssel.

   Du kannst dich unter https://deepmind.google.com/science/alphagenome/ für einen Schlüssel registrieren. Du MUSST das sichere Credentials-Protokoll aus der credentials-Skill verwenden, um nach diesem Schlüssel zu suchen und ihn anzufordern, falls diese Skill für die Anfrage des Benutzers relevant erscheint.

5. ALPHAGENOME_GTF_PATH (Optional): Beschleunige die Gen-/Transkriptsuche, indem du auf eine lokale Kopie der GTF-Feather-Datei verweist, anstatt sie von GCS herunterzuladen:

   echo "ALPHAGENOME_GTF_PATH=/pfad/zu/lokaler/gencode.v46.annotation.gtf.gz.feather" >> ~/.env
   

Kernregeln

• Führe NIEMALS python3 oder python3 -c direkt aus. Das System-Python hat nicht unbedingt pandas, numpy und andere wichtige Abhängigkeiten. Verwende IMMER uv run, um ALLEN Python-Code auszuführen – einschließlich Skripte, Ad-hoc-Analysedateien und Einzeiler. Versuche nicht, pip install auszuführen oder neue Venvs zu erstellen – uv verwaltet automatisch eine isolierte Umgebung.
• Nur offline: Verwende NIEMALS externe APIs (z.B. MyGene.info, Ensembl REST) für die Gen-/Transkriptsuche. Verwende lookup_gene_info.py mit der lokalen GTF. Falls dies fehlschlägt, behebe die Umgebung/Pfade, wechsle nicht zu externen APIs.
• API-Schlüssel erforderlich: ALPHAGENOME_API_KEY muss gesetzt sein, bevor ein Skript ausgeführt wird.
• Benachrichtigung: Falls diese Skill verwendet wird, stelle sicher, dass dies in der Ausgabe erwähnt wird.
• Berichtsformat: Verwende immer die Vorlagen in docs/report-templates.md zur Erstellung von Analyseberichten und stelle sicher, dass die Tabelle der Top-Treffer aus dem Discovery-Scan enthalten ist.

Umgebungseinrichtung & Fehlerbehebung

Python-Umgebung

Alle Skripte müssen mit uv run ausgeführt werden, das eine isolierte virtuelle Umgebung mit den korrekten Abhängigkeiten via uv verwaltet.

uv run <skriptname> [argumente...]

Für Ad-hoc-Skripte (z.B. Inline-Analysecode, der in eine temporäre Datei gespeichert wird), übergib den vollständigen Pfad anstelle eines kurzen Namens:

uv run --project $SKILL_DIR /tmp/meine_analyse.py --arg1 wert1

[!HINWEIS] Der erste Aufruf löst Abhängigkeiten auf und installiert sie (~10s). Nachfolgende Ausführungen verwenden die gecachte Umgebung und starten sofort. Der Cache befindet sich in ~/.cache/uv/.

Häufige Probleme

• Spaltennamen: tidy_scores und Metadaten verwenden oft gene_name (nicht gene_symbol) und output_type (nicht modality). Überprüfe immer df.columns vor dem Filtern.
• Große Gene: Gene > 500kb (z.B. USH2A) brechen die whole_gene-Ansicht. Verwende stattdessen --view detail oder manuelle regionale Fenster.
• Sashimi-Strangfehler: plot_components.Sashimi akzeptiert KEIN strand-Argument direkt. Filtere stattdessen die Eingabe-Tracks.
• KeyError: 'ontology_curie': Nicht alle Tracks haben ontology_curie. Überprüfe track.metadata.columns vor dem Filtern.
• Python-Pfad: Falls exec: "python": executable file not found auftritt, stelle sicher, dass du uv run anstelle von bloßem python/python3 verwendest.
• NotImplementedError (pandas): „iLocation based boolean indexing on an integer type is not available“. Dies tritt auf, wenn boolesche Masken mit .iloc auf integer-indizierten DataFrames in neueren pandas-Versionen verwendet werden. Lösung: Konvertiere boolesche Masken in Integer-Indizes mit np.flatnonzero(mask).
• GTF Feather Groß-/Kleinschreibung: Die AlphaGenome GTF Feather-Datei verwendet Großgeschriebene Spaltennamen (Feature, Start, End, Strand), anders als Standard-GTF-Dateien. Überprüfe immer df.columns, falls KeyErrors auftreten.
• score_variant Ontologie-Filterung: score_variant akzeptiert KEINE ontology_terms als Argument. Du musst die zurückgegebenen AnnData-Objekte manuell filtern, indem du adata.var-Spalten überprüfst. Im Gegensatz dazu akzeptiert predict_variant ontology_terms direkt.
• Sashimi-Zoom-Logik: Um sicherzustellen, dass „Skipping“-Bögen sichtbar sind, erweitere den Zoom auf die flankierenden Exons, anstatt sich allein auf die Überlappung von Junctions zu verlassen.
• Junction-Scores: Rohe Junction-Objekte aus prediction können einfache Intervalle sein. Verwende junction_data.get_junctions_to_plot(predictions=..., name=...), um Objekte mit dem .k-Attribut (Häufigkeit/Score) abzurufen.
• uv nicht gefunden: Falls exec: uv: not found, befolge die Installationsanweisungen in Voraussetzungen.
• Registry-Authentifizierungsfehler (401): Falls uv mit 401 Unauthorized für eine private Registry fehlschlägt, setze vor dem Ausführen des Skripts UV_INDEX_URL=https://pypi.org/simple.

Referenzen

• alphagenome-api.md — API-Referenz und Code-Muster
• interpretation-guide.md — Interpretationsleitfaden, Score-Größenregeln, ISM und Checkliste
• report-templates.md — Vollständige Berichtsvorlagen
• scripts/visualize_variant_effects.py — Einzelvarianten-Visualisierungsvorlage (Ref/Alt-Vergleiche, Spleißen)
  • Spleißen-Zoom-Strategie: Verwendet einen Hybridansatz für optimale Sichtbarkeit:
    1. Basisintervall: Variante +/- 1 nachgeschaltetes und vorgeschaltetes Exon (struktureller Kontext).
    2. Junction-Erweiterung: Erweitert auf die volle Spannweite jeder signifikanten Spleiß-Junction (z.B. Exon-Skipping-Ereignisse, die mehrere Exons überspannen).
    3. Anker-Erzwingung: Stellt sicher, dass die Exons, die diese langen Junctions verankern, vollständig sichtbar sind. Lektion: Einfache feste Fenster (z.B. 2kb) oder die Logik des nächsten Exons versagen oft bei Skipping-Ereignissen. Verwende immer die beobachteten Junction-Daten, um die Zoomstufen zu bestimmen.
• examples/splicing/ — Beispiele für Spleißanalysen
• examples/model_limitation_RNU4ATAC/ — Fallstudie zu ncRNA-Strukturbegrenzungen
• examples/polyadenylation_HBA2/ — Fallstudie zu 3' UTR / Polyadenylierung
• examples/regulatory/ — Beispiele für regulatorische Varianten
• examples/negative_result_GATA4/ — Negative Ergebnisse (mathematisches Artefakt)
• examples/negative_result_TGFB3/ — Negative Ergebnisse (Proxies)
• scripts/lookup_gene_info.py — Gen- & Transkriptsuche
• scripts/resolve_ontology_terms.py — Auflösung von Ontologiebegriffen (UBERON/CL-IDs)

---

Code-Muster

Breiter Discovery-Scan

Verwende score_variant über differential scorer hinweg, um unerwartete Gewebeeffekte zu entdecken.

from alphagenome.models import dna_client
from alphagenome.models import variant_scorers
from alphagenome.data import genome
import os
import pandas as pd
import dotenv

# Lade Umgebungsvariablen aus ~/.env
dotenv.load_dotenv(os.path.expanduser('~/.env'))

# Richte API-Schlüssel und Client ein
dna_model = dna_client.create(api_key=os.environ.get('ALPHAGENOME_API_KEY'),
                              address='dns:///gdmscience.googleapis.com:443')

# Definiere Variante (Beispiel)
variant_str = "chr2:1234:A>C"
chrom, pos_str, ref_alt = variant_str.split(':')
ref, alt = ref_alt.split('>')
pos = int(pos_str)

# Verwende unterstützte Sequenzlänge (z.B. 2**20 für optimale Leistung)
SEQ_LENGTH = 2**20
interval = genome.Interval(chrom, pos - SEQ_LENGTH // 2, pos + SEQ_LENGTH // 2)
variant = genome.Variant(chrom, pos, ref, alt)

scorers = [
    variant_scorers.RECOMMENDED_VARIANT_SCORERS[m]
    for m in variant_scorers.RECOMMENDED_VARIANT_SCORERS
    if "ACTIVE" not in m and "CAGE" not in m and "PROCAP" not in m
]

print(f"Bewerte Variante {variant_str}...")
scores_list = dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)

# Verarbeite und zeige Ergebnisse
all_dfs = []
for score_adata in scores_list:
    df = variant_scorers.tidy_scores([score_adata], match_gene_strand=True)
    if df is not None:
        all_dfs.append(df)

if all_dfs:
    df = pd.concat(all_dfs)
    significant = df[df['quantile_score'].abs() > 0.995]
    ranked = significant.sort_values('raw_score', key=abs, ascending=False)
    print("Top signifikante Treffer:")
    print(ranked[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

Erweiterte Suche nach krankheitsrelevanten Geweben

# Definiere Schlüsselwörter basierend auf dem Krankheitskontext
disease_keywords = ["leber", "hepatozyt"]

# Filtere nach Übereinstimmungen
mask = df['biosample_name'].str.contains('|'.join(disease_keywords), case=False, na=False)

relevant_hits = df[mask].sort_values('raw_score', key=abs, ascending=False)
print(f"\n--- Erweiterte Analyse (Schlüsselwörter: {disease_keywords}) ---")
print(relevant_hits.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

Workflow-Checkliste

Variantenanalyse-Fortschritt:
- [ ] Schritt 0: Goldene Beispiele überprüfen (VERPFLICHTEND)
- [ ] Schritt 1: Ausgabeordner erstellen und einrichten
- [ ] Schritt 2: Benutzerabfrage parsen & recherchieren
- [ ] Schritt 3: Gewebe & Modalitäten auflösen
- [ ] Schritt 4: Visualisieren & Plots speichern
- [ ] Schritt 5: Vorhersagen analysieren (Plots ansehen, kein Code). VERPFLICHTEND: Lies [interpretation-guide.md](docs/interpretation-guide.md) vor der Ergebnisinterpretation.
- [ ] Schritt 6: Bericht schreiben, als `report.md` speichern (VERPFLICHTEND)
- [ ] Schritt 7: Selbstkritik (`report.md` ansehen, um Links & Behauptungen zu überprüfen)
- [ ] Schritt 8: `report.md` als Artefakt ausgeben

---

Mehrvarianten-Workflow

Falls mehrere Varianten angegeben sind, erstelle Unter-Agents, um jede Variantenanalyse durchzuführen, und fasse dann jede report.md zu einem einzigen Bericht zusammen.

Skript-Referenz

Skript	Zweck
lookup_gene_info	Umfassende Gen- und Transkriptsuche mittels
: : GTF-Daten :
resolve_ontology_terms	Biologische Begriffe → UBERON/CL/EFO-IDs
visualize_variant_effects	REF/ALT-Visualisierung (Expression, regulatorisch,
: : Spleißen) :
analyze_ism	In-Silico-Mutagenese-SeqLogo-Generierung
interpret_splicing	Quantitative Spleißanalyse (Delta-Scores,
: : Junctions) :
visualize_genome_tracks	Genomische Track-Visualisierung für eine Region