Analyse de variantes utilisant AlphaGenome

Prérequis

uv: Lisez la skill uv et suivez ses instructions de configuration pour vérifier que uv est installé et dans le PATH.
Notification utilisateur: Si LICENSE_NOTIFICATION.txt n'existe pas déjà dans ce répertoire de skill, alors (1) notifiez l'utilisateur de manière visible à consulter les conditions à https://deepmind.google.com/science/alphagenome/, puis (2) créez le fichier enregistrant le texte de notification et l'horodatage.
Fichier .env: Assurez-vous que le fichier .env existe dans votre répertoire personnel. Créez-en un s'il n'existe pas.
ALPHAGENOME_API_KEY: Cette skill nécessite une clé API pour fonctionner. Vous devez demander à l'utilisateur une clé API si cette skill semble pertinente pour sa demande et que vous n'en avez pas dans .env. L'utilisateur peut s'inscrire à https://deepmind.google.com/science/alphagenome/. Ne demandez PAS à l'utilisateur de coller sa clé dans le chat (cela pourrait divulguer la clé dans le contexte de l'agent). Expliquez plutôt qu'une clé est nécessaire pour utiliser AlphaGenome et donnez à l'utilisateur cette commande en remplaçant ENV_FILE par le chemin littéral résolu vers le fichier .env :
```
printf "Enter AlphaGenome API key (typing hidden): " && read -s key && echo && echo "ALPHAGENOME_API_KEY=$key" >> "ENV_FILE" && echo "Saved."
```
Les scripts chargent automatiquement les identifiants via dotenv. NE JAMAIS lire, afficher ou inspecter le fichier .env ou ses variables (par ex. pas de cat, grep, echo, printenv ou os.environ.get sur les clés). Les identifiants doivent rester hors du contexte de l'agent.

Lors de l'exécution en sandbox, dotenv.load_dotenv() n'aura aucun effet, et le sandbox lira les identifiants et les injectera directement.

Règles fondamentales

NE JAMAIS exécuter python3 ou python3 -c directement. Le Python système n'a pas nécessairement pandas, numpy et autres dépendances clés. TOUJOURS utiliser uv run pour exécuter TOUT code Python — y compris les scripts, les fichiers d'analyse ad-hoc et les one-liners. Ne tentez pas de pip install ou de créer de nouveaux venvs — uv gère automatiquement un environnement isolé.
Hors ligne uniquement: NE JAMAIS utiliser d'API externes (par ex. MyGene.info, Ensembl REST) pour les recherches de gène/transcrit. Utilisez lookup_gene_info.py avec le GTF local. Si cela échoue, corrigez l'environnement/chemins, ne basculez pas vers des API externes.
La clé API est obligatoire: ALPHAGENOME_API_KEY doit être définie avant d'exécuter n'importe quel script (en sandbox, les identifiants sont automatiquement injectés).
Notification: Si cette skill est utilisée, assurez-vous que cela est mentionné dans la sortie.
Format de rapport: Toujours utiliser les modèles dans docs/report-templates.md pour générer des rapports d'analyse, et s'assurer d'inclure le tableau des principaux résultats du scan de découverte.

Configuration de l'environnement et dépannage

Environnement Python

Tous les scripts doivent être exécutés à l'aide de uv run, qui gère un environnement virtuel isolé avec les dépendances correctes via uv.

uv run <script_name> [args...]

Pour les scripts ad-hoc (par ex. code d'analyse inline enregistré dans un fichier temporaire), passez le chemin complet plutôt qu'un nom court :

uv run --project $SKILL_DIR /tmp/my_analysis.py --arg1 val1

[!NOTE] Le premier appel résout et installe les dépendances (~10s). Les exécutions suivantes utilisent l'environnement en cache et démarrent instantanément. Le cache se trouve dans ~/.cache/uv/.

Problèmes courants

Noms de colonnes: tidy_scores et les métadonnées utilisent souvent gene_name (pas gene_symbol) et output_type (pas modality). Toujours inspecter df.columns avant de filtrer.
Gènes volumineux: Les gènes > 500kb (par ex. USH2A) cassent la vue whole_gene. Utilisez --view detail ou des fenêtres régionales manuelles à la place.
Erreur Sashimi Strand: plot_components.Sashimi N'ACCEPTE PAS d'argument strand directement. Filtrez les pistes d'entrée à la place.
KeyError: 'ontology_curie': Pas toutes les pistes ont ontology_curie. Vérifiez track.metadata.columns avant de filtrer.
Chemin Python: Si exec: "python": executable file not found se produit, assurez-vous d'utiliser uv run au lieu de python/python3 direct.
NotImplementedError (pandas): « iLocation based boolean indexing on an integer type is not available ». Cela se produit lors de l'utilisation de masques booléens avec .iloc sur des DataFrames indexés par entier dans les versions plus récentes de pandas. Correction: Convertissez les masques booléens en indices entiers en utilisant np.flatnonzero(mask).
Sensibilité à la casse du fichier Feather GTF: Le fichier AlphaGenome GTF Feather utilise des noms de colonnes en majuscules (Feature, Start, End, Strand) contrairement aux fichiers GTF standard. Toujours vérifier df.columns si vous obtenez des KeyErrors.
Filtrage ontologie de score_variant: score_variant N'ACCEPTE PAS ontology_terms comme argument. Vous devez filtrer manuellement les objets AnnData retournés en inspectant les colonnes adata.var. En contraste, predict_variant ACCEPTE ontology_terms directement.
Logique de zoom Sashimi: Pour assurer la visibilité des arcs « skip », élargissez le zoom pour inclure les exons flanquants plutôt que de vous fier uniquement au chevauchement de jonction.
Scores de jonction: Les objets Junction bruts issus de prediction peuvent être de simples Intervals. Utilisez junction_data.get_junctions_to_plot(predictions=..., name=...) pour récupérer des objets avec l'attribut .k (abondance/score).
uv non trouvé: Si exec: uv: not found, suivez les instructions d'installation dans Prérequis.
Erreur d'authentification du registre (401): Si uv échoue avec 401 Unauthorized pour un registre privé, définissez UV_INDEX_URL=https://pypi.org/simple avant d'exécuter le script.

Références

alphagenome-api.md — Référence API et modèles de code
interpretation-guide.md — Guide d'interprétation, règles de magnitude des scores, ISM et checklist.
report-templates.md — Modèles de rapport complets
scripts/visualize_variant_effects.py — Modèle de visualisation monovariante (comparaisons Ref/Alt, Épissage).
- Stratégie de zoom d'épissage: Utilise une approche hybride pour une visibilité optimale :
  1. Intervalle de base: Variante +/- 1 exon en aval et en amont (contexte structurel).
  2. Expansion de jonction: S'élargit pour inclure l'étendue complète de toute jonction d'épissage significative (par ex. événements d'exon skipping qui couvrent plusieurs exons).
  3. Renforcement d'ancrage: Assure que les exons ancrant ces longues jonctions sont entièrement visibles. Leçon: Les fenêtres fixes simples (par ex. 2kb) ou la logique de l'exon le plus proche échouent souvent pour les événements de skipping. Toujours utiliser les données de jonction observées pour piloter les niveaux de zoom.
examples/splicing/ — Exemples d'analyse d'épissage
examples/model_limitation_RNU4ATAC/ — Étude de cas de limitation de structure ncRNA
examples/polyadenylation_HBA2/ — Cas d'étude 3' UTR / polyadénylation
examples/regulatory/ — Exemples de variantes régulatrices
examples/negative_result_GATA4/ — Résultats négatifs (artefact mathématique)
examples/negative_result_TGFB3/ — Résultats négatifs (proxies)
scripts/lookup_gene_info.py — Recherche de gène et transcrit
scripts/resolve_ontology_terms.py — Résolution de termes ontologiques (IDs UBERON/CL)

Modèles de code

Scan de découverte large

Utilisez score_variant sur les scoreurs différentiels uniquement pour découvrir des effets tissulaires inattendus.

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

# Configurer clé API et client
dna_model = dna_client.create(api_key=os.environ.get('ALPHAGENOME_API_KEY'),
                              address='dns:///gdmscience.googleapis.com:443')

# Définir variante (exemple)
variant_str = "chr2:1234:A>C"
chrom, pos_str, ref_alt = variant_str.split(':')
ref, alt = ref_alt.split('>')
pos = int(pos_str)

# Utiliser la longueur de séquence supportée (par ex. 2**20 pour performances optimales)
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"Scoring variant {variant_str}...")
scores_list = dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)

# Traiter et afficher les résultats
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 Significant Hits:")
    print(ranked[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

Recherche étendue de tissus pertinents pour la maladie

# Définir des mots-clés basés sur le contexte de la maladie
disease_keywords = ["liver", "hepatocyte"]

# Filtrer pour toute correspondance
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--- Extended Analysis (Keywords: {disease_keywords}) ---")
print(relevant_hits.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

Checklist de workflow

Progression de l'analyse de variante :
- [ ] Étape 0: Examiner les exemples référence (OBLIGATOIRE)
- [ ] Étape 1: Créer dossier de sortie et configuration
- [ ] Étape 2: Analyser la requête utilisateur et recherche
- [ ] Étape 3: Résoudre les tissus et modalités
- [ ] Étape 4: Visualiser et enregistrer les graphiques
- [ ] Étape 5: Analyser les prédictions (consulter graphiques, sans code). OBLIGATOIRE: Lire [interpretation-guide.md](docs/interpretation-guide.md) avant d'interpréter les résultats.
- [ ] Étape 6: Écrire le rapport, l'enregistrer sous `report.md` (OBLIGATOIRE)
- [ ] Étape 7: Auto-critique (consulter `report.md` pour vérifier les liens et affirmations)
- [ ] Étape 8: Créer un artefact à partir de `report.md`

Workflow multi-variante

Si plusieurs variantes sont spécifiées, lancez des sous-agents pour exécuter chaque analyse de variante puis synthétisez chaque report.md dans un rapport unique.

Référence des scripts

Script	Objectif
`lookup_gene_info`	Recherche complète de gène et transcrit

alphagenome-single-variant-analysis