google-deepmind/science-skills

Analyse de variants avec AlphaGenome

Prérequis

1. uv : Lisez la compétence uv et suivez ses instructions d'installation pour vous assurer que uv est installé et dans le PATH.

2. Notification utilisateur : Si le fichier .licenses/alphagenome_single_variant_analysis_LICENSE.txt n'existe pas déjà dans le répertoire racine du projet, alors (1) informez l'utilisateur de manière visible de vérifier les conditions sur https://deepmind.google.com/science/alphagenome/, puis (2) créez le fichier en enregistrant le texte de notification et l'horodatage.

3. Fichier .env : Assurez-vous que le fichier .env existe dans votre répertoire personnel. Créez-en un s'il n'existe pas.

4. ALPHAGENOME_API_KEY : Cette compétence nécessite une clé API pour fonctionner.

   Vous pouvez enregistrer une clé sur https://deepmind.google.com/science/alphagenome/. Vous DEVEZ utiliser le protocole sécurisé des identifiants de la compétence credentials pour vérifier et demander cette clé si cette compétence semble pertinente pour la demande de l'utilisateur.

5. ALPHAGENOME_GTF_PATH (Optionnel) : Accélérez la recherche de gènes/transcrits en pointant vers une copie locale du fichier feather GTF au lieu de le télécharger depuis GCS :

   echo "ALPHAGENOME_GTF_PATH=/chemin/vers/local/gencode.v46.annotation.gtf.gz.feather" >> ~/.env
   

Règles fondamentales

• N'utilisez JAMAIS python3 ou python3 -c directement. Le Python système n'a pas nécessairement pandas, numpy et les autres dépendances clés. Utilisez TOUJOURS uv run pour exécuter TOUT code Python — y compris les scripts, les fichiers d'analyse ad-hoc et les one-liners. N'essayez pas de pip install ou de créer de nouveaux venvs — uv gère automatiquement un environnement isolé.
• Hors ligne uniquement : N'utilisez JAMAIS d'API externes (par ex., MyGene.info, Ensembl REST) pour la recherche de gènes/transcrits. Utilisez lookup_gene_info.py avec le GTF local. En cas d'échec, corrigez l'environnement/les chemins, ne passez pas aux API externes.
• Clé API requise : ALPHAGENOME_API_KEY doit être définie avant d'exécuter tout script.
• Notification : Si cette compétence est utilisée, assurez-vous de le mentionner dans la sortie.
• Format du rapport : Utilisez toujours les modèles dans docs/report-templates.md pour générer les rapports d'analyse, et assurez-vous d'inclure le tableau des meilleurs résultats de l'analyse exploratoire.

Configuration de l'environnement et dépannage

Environnement Python

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

uv run <nom_du_script> [args...]

Pour les scripts ad-hoc (par exemple, du code d'analyse en ligne sauvegardé dans un fichier temporaire), passez le chemin complet au lieu d'un nom court :

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

[!NOTE] La première invocation 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). Inspectez toujours df.columns avant de filtrer.
• Grands gènes : Les gènes de plus de 500 kb (par ex., USH2A) cassent la vue whole_gene. Utilisez --view detail ou des fenêtres régionales manuelles à la place.
• Erreur de brin Sashimi : plot_components.Sashimi n'accepte PAS d'argument strand directement. Filtrez plutôt les pistes d'entrée.
• KeyError: 'ontology_curie' : Toutes les pistes n'ont pas ontology_curie. Vérifiez track.metadata.columns avant de filtrer.
• Chemin Python : Si l'erreur exec: "python": executable file not found se produit, assurez-vous d'utiliser uv run au lieu de python/python3 nu.
• 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 récentes de pandas. Correctif : Convertissez les masques booléens en indices entiers avec np.flatnonzero(mask).
• Sensibilité à la casse du fichier Feather GTF : Le fichier Feather GTF d'AlphaGenome utilise des noms de colonnes en majuscules (Feature, Start, End, Strand) contrairement aux fichiers GTF standard. Vérifiez toujours df.columns si vous obtenez des KeyError.
• Filtrage d'ontologie de score_variant : score_variant n'accepte PAS ontology_terms comme argument. Vous devez filtrer les objets AnnData renvoyés manuellement en inspectant les colonnes adata.var. En revanche, predict_variant accepte ontology_terms directement.
• Logique de zoom Sashimi : Pour vous assurer que les arcs de "saut" sont visibles, étendez le zoom pour inclure les exons flanquants plutôt que de vous fier uniquement au chevauchement des jonctions.
• Scores des jonctions : Les objets Junction bruts de prediction peuvent être de simples Intervalles. Utilisez junction_data.get_junctions_to_plot(predictions=..., name=...) pour récupérer les objets avec l'attribut .k (abondance/score).
• uv introuvable : Si l'erreur exec: uv: not found se produit, suivez les instructions d'installation dans Prérequis.
• Erreur d'authentification de registre (401) : Si uv échoue avec une erreur 401 Non autorisé 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 liste de vérification.
• report-templates.md — Modèles de rapport complets
• scripts/visualize_variant_effects.py — Modèle de visualisation de variant unique (comparaisons Ref/Alt, épissage).
  • Stratégie de zoom pour l'épissage : Utilise une approche hybride pour une visibilité optimale :
    1. Intervalle de base : Variant +/- 1 exon en aval et en amont (contexte structurel).
    2. Extension des jonctions : S'étend pour inclure la portée totale de toute jonction d'épissage significative (par exemple, les événements de saut d'exon qui s'étendent sur plusieurs exons).
    3. Application des points d'ancrage : Garantit que les exons ancrant ces longues jonctions sont entièrement visibles. Leçon : Les fenêtres fixes simples (par exemple, 2 kb) ou la logique du plus proche exon échouent souvent pour les événements de saut. Utilisez toujours 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 sur la limitation de la structure des ARNnc
• examples/polyadenylation_HBA2/ — Étude de cas sur la région 3' UTR / Polyadénylation
• examples/regulatory/ — Exemples de variants régulateurs
• examples/negative_result_GATA4/ — Résultats négatifs (artefact mathématique)
• examples/negative_result_TGFB3/ — Résultats négatifs (proxys)
• scripts/lookup_gene_info.py — Recherche de gènes et de transcrits
• scripts/resolve_ontology_terms.py — Résolution de termes d'ontologie (identifiants UBERON/CL)

---

Modèles de code

Analyse exploratoire large

Utilisez score_variant avec 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
import dotenv

# Charger les variables d'environnement depuis ~/.env
dotenv.load_dotenv(os.path.expanduser('~/.env'))

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

# Définir le variant (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 une longueur de séquence prise en charge (par exemple, 2**20 pour des 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"Scorage du variant {variant_str}...")
scores_list = dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)

# Traitement et affichage des 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("Meilleurs résultats significatifs :")
    print(ranked[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

Recherche étendue pour les tissus pertinents pour la maladie

# Définir des mots-clés basés sur le contexte de la maladie
mots_cles_maladie = ["foie", "hépatocyte"]

# Filtrer pour toute correspondance
masque = df['biosample_name'].str.contains('|'.join(mots_cles_maladie), case=False, na=False)

resultats_pertinents = df[masque].sort_values('raw_score', key=abs, ascending=False)
print(f"\n--- Analyse étendue (mots-clés : {mots_cles_maladie}) ---")
print(resultats_pertinents.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

Liste de vérification du flux de travail

Progression de l'analyse de variants :
- [ ] Étape 0 : Examiner les exemples en or (OBLIGATOIRE)
- [ ] Étape 1 : Créer le dossier de sortie et la configuration
- [ ] Étape 2 : Analyser la requête utilisateur et rechercher
- [ ] Étape 3 : Résoudre les tissus et les modalités
- [ ] Étape 4 : Visualiser et sauvegarder les graphiques
- [ ] Étape 5 : Analyser les prédictions (afficher les graphiques, pas de code). OBLIGATOIRE : Lisez [interpretation-guide.md](docs/interpretation-guide.md) avant d'interpréter les résultats.
- [ ] Étape 6 : Rédiger le rapport, le sauvegarder sous `report.md` (OBLIGATOIRE)
- [ ] Étape 7 : Auto-critique (consultez `report.md` pour vérifier les liens et les affirmations)
- [ ] Étape 8 : Créer un artéfact à partir de `report.md`

---

Flux de travail multi-variants

Si plusieurs variants sont spécifiés, créez des sous-agents pour exécuter chaque analyse de variant, puis synthétisez chaque report.md en un seul rapport.

Référence des scripts

Script	Objectif
lookup_gene_info	Recherche complète de gènes et de transcrits en
: : utilisant les données GTF :
resolve_ontology_terms	Termes biologiques → identifiants UBERON/CL/EFO
visualize_variant_effects	Visualisation REF/ALT (expression, régulation,
: : épissage) :
analyze_ism	Génération de SeqLogo par mutagénèse in silico
interpret_splicing	Analyse quantitative de l'épissage (scores
: : delta, jonctions) :
visualize_genome_tracks	Visualisation de pistes génomiques pour une
: : région :