Análisis de Variantes con AlphaGenome - Science Skills

Análisis de Variantes usando AlphaGenome

Prerrequisitos

1. uv: Lea el skill uv y siga sus Instrucciones de configuración para asegurar que uv esté instalado y en PATH.

2. Notificación al Usuario: Si el archivo .licenses/alphagenome_single_variant_analysis_LICENSE.txt no existe en el directorio raíz del espacio de trabajo, entonces (1) notifique prominentemente al usuario que revise los términos en https://deepmind.google.com/science/alphagenome/, luego (2) cree el archivo registrando el texto de notificación y la marca de tiempo.

3. Archivo .env: Asegúrese de que el archivo .env exista en su directorio personal. Cree uno si no existe.

4. ALPHAGENOME_API_KEY: Este skill requiere una clave API para funcionar.

   Puede registrarse para obtener una clave en https://deepmind.google.com/science/alphagenome/. DEBE usar el protocolo seguro de credenciales del skill credentials para verificar y solicitar esta clave si este skill parece relevante para la solicitud del usuario.

5. ALPHAGENOME_GTF_PATH (Opcional): Acelere la búsqueda de genes/transcripciones apuntando a una copia local del archivo feather GTF en lugar de descargarlo desde GCS:

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

Reglas Principales

• NUNCA ejecute python3 o python3 -c directamente. El Python del sistema no necesariamente tiene pandas, numpy y otras dependencias clave. Use SIEMPRE uv run para ejecutar TODO el código Python — incluyendo scripts, archivos de análisis ad-hoc y líneas únicas. No intente pip install ni cree nuevos venvs — uv maneja un entorno aislado automáticamente.
• Solo Sin Conexión: NUNCA use APIs externas (por ejemplo, MyGene.info, Ensembl REST) para la búsqueda de genes/transcripciones. Use lookup_gene_info.py con el GTF local. Si falla, arregle el entorno/rutas, no cambie a APIs externas.
• Clave API requerida: ALPHAGENOME_API_KEY debe estar configurada antes de ejecutar cualquier script.
• Notificación: Si se usa este skill, asegúrese de mencionarlo en la salida.
• Formato del Informe: Use siempre las plantillas en docs/report-templates.md para generar informes de análisis, y asegúrese de incluir la tabla de los principales aciertos del escaneo de descubrimiento.

Configuración del Entorno y Solución de Problemas

Entorno de Python

Todos los scripts deben ejecutarse usando uv run, que maneja un entorno virtual aislado con las dependencias correctas a través de uv.

uv run <nombre_del_script> [argumentos...]

Para scripts ad-hoc (por ejemplo, código de análisis en línea guardado en un archivo temporal), pase la ruta completa en lugar de un nombre corto:

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

[!NOTA] La primera invocación resuelve e instala dependencias (~10s). Las ejecuciones posteriores usan el entorno en caché e inician instantáneamente. El caché reside en ~/.cache/uv/.

Problemas Comunes

• Nombres de Columnas: tidy_scores y los metadatos a menudo usan gene_name (no gene_symbol) y output_type (no modality). Siempre inspeccione df.columns antes de filtrar.
• Genes Grandes: Genes mayores a 500kb (por ejemplo, USH2A) rompen la vista de whole_gene. Use --view detail o ventanas regionales manuales en su lugar.
• Error de Hebra en Sashimi: plot_components.Sashimi NO acepta un argumento strand directamente. Filtre las pistas de entrada en su lugar.
• KeyError: 'ontology_curie': No todas las pistas tienen ontology_curie. Verifique track.metadata.columns antes de filtrar.
• Ruta de Python: Si ocurre exec: "python": executable file not found, asegúrese de estar usando uv run en lugar de python/python3 simples.
• NotImplementedError (pandas): "iLocation based boolean indexing on an integer type is not available". Esto ocurre al usar máscaras booleanas con .iloc en DataFrames indexados por enteros en versiones más recientes de pandas. Solución: Convierta máscaras booleanas a índices enteros usando np.flatnonzero(mask).
• Sensibilidad de Mayúsculas en Archivo GTF Feather: El archivo GTF Feather de AlphaGenome usa nombres de columna en mayúscula (Feature, Start, End, Strand) a diferencia de los archivos GTF estándar. Siempre verifique df.columns si obtiene KeyErrors.
• Filtrado de ontología en score_variant: score_variant NO acepta ontology_terms como argumento. Debe filtrar los objetos AnnData devueltos manualmente inspeccionando las columnas de adata.var. En contraste, predict_variant SÍ acepta ontology_terms directamente.
• Lógica de Zoom en Sashimi: Para asegurar que los arcos de "salto" sean visibles, amplíe el zoom para incluir los exones flanqueantes en lugar de confiar solo en la superposición de uniones.
• Puntuaciones de Uniones: Los objetos Junction sin procesar de prediction pueden ser Intervalos simples. Use junction_data.get_junctions_to_plot(predictions=..., name=...) para recuperar objetos con el atributo .k (abundancia/puntuación).
• uv No Encontrado: Si ocurre exec: uv: not found, siga las instrucciones de instalación en Prerrequisitos.
• Error de Autenticación de Registro (401): Si uv falla con 401 No Autorizado para un registro privado, establezca UV_INDEX_URL=https://pypi.org/simple antes de ejecutar el script.

Referencias

• alphagenome-api.md — Referencia de API y patrones de código
• interpretation-guide.md — Guía de interpretación, reglas de magnitud de puntuación, ISM y lista de verificación.
• report-templates.md — Plantillas de informe completas
• scripts/visualize_variant_effects.py — Plantilla de visualización de variantes individuales (Comparaciones Ref/Alt, Splicing).
  • Estrategia de Zoom de Splicing: Usa un Enfoque Híbrido para una visibilidad óptima:
    1. Intervalo Base: Variante +/- 1 exón corriente abajo y arriba (Contexto Estructural).
    2. Expansión de Unión: Se expande para incluir el tramo completo de cualquier unión de splicing significativa (por ejemplo, eventos de salto de exón que abarcan múltiples exones).
    3. Aplicación de Anclaje: Asegura que los exones que anclan estas uniones largas sean completamente visibles. Lección: Las ventanas fijas simples (por ejemplo, 2kb) o la lógica del exón más cercano a menudo fallan para eventos de salto. Siempre use los datos de unión observados para determinar los niveles de zoom.
• examples/splicing/ — Ejemplos de análisis de splicing
• examples/model_limitation_RNU4ATAC/ — Estudio de caso de limitación de estructura de ncRNA
• examples/polyadenylation_HBA2/ — Estudio de caso de UTR 3' / Poliadenilación
• examples/regulatory/ — Ejemplos de variantes reguladoras
• examples/negative_result_GATA4/ — Resultados negativos (artefacto matemático)
• examples/negative_result_TGFB3/ — Resultados negativos (proxy)
• scripts/lookup_gene_info.py — Búsqueda de genes y transcripciones
• scripts/resolve_ontology_terms.py — Resolución de términos de ontología (IDs UBERON/CL)

---

Patrones de Código

Escaneo de Descubrimiento Amplio

Use score_variant a través de scorers diferenciales únicamente para descubrir efectos tisulares inesperados.

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

# Cargar variables de entorno desde ~/.env
dotenv.load_dotenv(os.path.expanduser('~/.env'))

# Configurar Clave API y Cliente
dna_model = dna_client.create(api_key=os.environ.get('ALPHAGENOME_API_KEY'),
                              address='dns:///gdmscience.googleapis.com:443')

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

# Usar longitud de secuencia compatible (por ejemplo, 2**20 para rendimiento óptimo)
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"Puntuando variante {variant_str}...")
scores_list = dna_model.score_variant(interval=interval, variant=variant, variant_scorers=scorers)

# Procesar y Mostrar Resultados
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("Principales Aciertos Significativos:")
    print(ranked[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

Búsqueda Extendida para Tejidos Relevantes a Enfermedades

# Definir palabras clave según el contexto de la enfermedad
palabras_clave = ["hígado", "hepatocito"]

# Filtrar para cualquier coincidencia
mascara = df['biosample_name'].str.contains('|'.join(palabras_clave), case=False, na=False)

aciertos_relevantes = df[mascara].sort_values('raw_score', key=abs, ascending=False)
print(f"\n--- Análisis Extendido (Palabras Clave: {palabras_clave}) ---")
print(aciertos_relevantes.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

Lista de Verificación del Flujo de Trabajo

Progreso del Análisis de Variantes:
- [ ] Paso 0: Revisar Ejemplos de Referencia (OBLIGATORIO)
- [ ] Paso 1: Crear Carpeta de Salida y Configuración
- [ ] Paso 2: Analizar Consulta del Usuario e Investigar
- [ ] Paso 3: Resolver Tejidos y Modalidades
- [ ] Paso 4: Visualizar y Guardar Gráficos
- [ ] Paso 5: Analizar Predicciones (ver gráficos, sin código). OBLIGATORIO: Leer [interpretation-guide.md](docs/interpretation-guide.md) antes de interpretar resultados.
- [ ] Paso 6: Escribir Informe, guardarlo como `report.md` (OBLIGATORIO)
- [ ] Paso 7: Autocrítica (ver `report.md` para verificar enlaces y afirmaciones)
- [ ] Paso 8: Crear artefacto a partir de `report.md`

---

Flujo de Trabajo Multi-Variante

Si se especifican múltiples variantes, genere subagentes para ejecutar cada análisis de variante y luego sintetice cada report.md en un solo informe.

Referencia de Scripts

Script	Propósito
lookup_gene_info	Búsqueda completa de genes y transcripciones usando
: : datos GTF :
resolve_ontology_terms	Términos biológicos → IDs UBERON/CL/EFO
visualize_variant_effects	Visualización REF/ALT (expresión, regulación,
: : splicing) :
analyze_ism	Generación de SeqLogo de Mutagénesis In-Silico
interpret_splicing	Análisis cuantitativo de splicing (puntuaciones
: : delta, uniones) :
visualize_genome_tracks	Visualización de pistas genómicas para una región