google-deepmind/science-skills

Configuración de enlaces profundos y URL de AlphaGenome Atlas

Construya y valide enlaces profundos para la aplicación web AlphaGenome Atlas (https://deepmind.google.com/science/alphagenome/atlas).

URL base: https://deepmind.google.com/science/alphagenome/atlas

[!IMPORTANT] Enlace profundo obligatorio al Atlas con puntuaciones de variantes: Siempre que presente, discuta o califique variantes genéticas, DEBE proporcionar siempre enlaces profundos funcionales al AlphaGenome Atlas. Use scripts/alphagenome_atlas_links.py para automatizar la generación de enlaces y tablas.

---

Requisitos previos

# 1. Enlace de exploración de variante única:
uv run scripts/alphagenome_atlas_links.py variant "chr9:128225994:G>A" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 2. Enlace de locus / intervalo genómico:
uv run scripts/alphagenome_atlas_links.py locus "chr11:5288500-5290500" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 3. Formatear tabla de registros de variantes candidatas (con enlaces incrustados):
uv run scripts/alphagenome_atlas_links.py table --input top_variants.json --biosample K562

# 4. Construir enlace de predicciones de pista Ref vs. Alt (/atlas/track-predictions):
uv run scripts/alphagenome_atlas_links.py track-predictions \
  --variant "chr15:42387805:C>G" \
  --gene CAPN3 \
  --biosample "Muscle_Skeletal"

---

2. Parámetros de consulta URL

• q (string, Requerido): Objetivo de búsqueda principal. Admite intervalos cerrados 1-based (chr11:5288500-5290500), símbolos de genes (BRCA1), IDs de Ensembl (ENSG00000012048), o variantes 1-based (chr7:27170000:A>G).
• m (enum, Opcional): Modo de vista. Por defecto es entity para genes/variantes y locus para intervalos de coordenadas. Use variant para consultas de variantes. (Permitidos: locus, entity, variant, motifs).
• i (string, Opcional): Intervalo de zoom del viewport centrado en formato cerrado 1-based chr:inicio-fin (ej. chr11:5289310-5289690). Requerido para el renderizado automático de motivos.
• f (string, Opcional): Predicados de filtro separados por comas en formato CLAVE:VALOR (ej. BIOSAMPLE_NAME:K562,SCORER_MODALITY:RNA-seq,ASSAY_TRANSCRIPTOR_FACTOR:GATA1). Controla las filas visibles del mapa de calor.
• lItems (string, Opcional): Secuencia de elementos de diseño, conmutador de pista de puntuación AVI (avi), mapas de calor de sección y lista de pistas ancladas (ej. avi,section:RNA_SEQ,section:DNASE,pinned:<TrackKey>).
• scores (string, Opcional): Lista separada por comas de tokens ScoreId para la página de comparación /atlas/track-predictions (ej. <ScoreId1>,<ScoreId2>).
• md (enum, Opcional): Selector de pestaña de modalidad activa en la vista de predicciones de pista (RNA_SEQ, SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, DNASE).
• tpRenames (string, Opcional): Anulaciones de título personalizadas para predicciones de puntuación específicas (ScoreId:CustomTitle).
• tpLegendTitle (string, Opcional): Título personalizado de la leyenda para la tarjeta gráfica de predicciones de pista (ej. Predicted Gene Expression).

[!IMPORTANT] Formato de consulta de variante: Las variantes en q deben usar estrictamente el formato chr:pos_1_based:ref>alt (ej. chr7:27170000:A>G o codificado en URL chr7:27170000:A%3EG, donde la posición es 1-based). No use alelos separados por dos puntos (A:G) ni rsIDs de dbSNP (los rsIDs no son compatibles).

---

3. Filtrado multimodal y el problema del grupo de ensayo (f)

Grupos de filtro y evaluación booleana

Los filtros en f se asignan a tres grupos de evaluación principales:

• Grupo Biosample (BIOSAMPLE_NAME, BIOSAMPLE_TYPE): Se evalúa con lógica AND.
• Grupo Assay (SCORER_MODALITY, ASSAY_TRANSCRIPTOR_FACTOR, ASSAY_HISTONE_MARK): Se evalúa con lógica OR.
• Grupo Gene (GENE_NAME): Se evalúa con lógica OR.

⚠️ Regla de filtrado multimodal obligatorio

Las pistas RNA-seq y DNase no tienen código de factor de transcripción (transcriptionFactorCode === ""). Si f contiene solo filtros ASSAY_TRANSCRIPTOR_FACTOR en el grupo Assay, las pistas RNA-seq y DNase fallan en la evaluación del grupo Assay y se ocultan del mapa de calor.

Para mostrar las pistas RNA-seq y DNase junto con factores de transcripción ChIP-seq específicos, incluya explícitamente SCORER_MODALITY:RNA-seq y SCORER_MODALITY:DNase en f (manejado automáticamente por scripts/alphagenome_atlas_links.py):

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

---

4. Configuración de diseño, puntuaciones AVI y pistas ancladas (lItems)

Trazado de puntuaciones AVI y secciones de modalidad

• Pista de impacto de variante AVI (avi): Incluir avi en lItems renderiza la pista de puntuación de impacto de variante AlphaGenome de nivel superior para el intervalo o la variante.
• Secciones de modalidad de base de datos (section:<MODALIDAD>): Las secciones renderizan mapas de calor completos sin anclar en todas las pistas coincidentes para esa modalidad (ej. section:RNA_SEQ, section:DNASE, section:CHIP_TF, section:ATAC, section:CAGE).

Pistas ancladas e instancias de motivo

[!NOTE] Directriz de motivo específico de pista: Las pistas Active-ISM ancladas con instancias de motivo y logotipos de Matriz de Peso de Contribución (CWM) solo deben agregarse cuando se soliciten específicamente para pistas individuales. Solo un subconjunto limitado de pistas (como pistas clave de ChIP-TF o RNA-seq relevantes para el locus) admiten y se benefician de las superposiciones de motivos anclados. Para enlaces de exploración estándar, se prefieren los mapas de calor de sección predeterminados (avi,section:RNA_SEQ,section:DNASE,section:CHIP_TF) sin pistas ancladas.

Las instancias de motivo y los logotipos CWM se renderizan exclusivamente en pistas de secuencia ancladas (ACTIVE_ISM o RAW_SCORES, no REF_SCORES) con resolución de par de bases. Los mapas de calor de sección general no activan el renderizado de huellas de motivo.

Esquema de clave de pista anclada

pinned:<NombreMetadatosPista>:<NúmeroCadena>:<NombreCortoScorer>:<Fuente>

Ejemplo de entrada lItems en una cadena de consulta URL sin procesar:

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

• <NombreMetadatosPista>: Nombre exacto de la pista del proto de metadatos (ej. EFO:0002067 TF ChIP-seq GATA1), codificado en porcentaje (%20 para espacios) en cadenas de consulta URL sin procesar (o sin codificar cuando se pasa a través de urllib.parse.urlencode).
• <NúmeroCadena>: 1 (STRAND_POSITIVE), 2 (STRAND_NEGATIVE), 3 (STRAND_UNSTRANDED).
• <NombreCortoScorer>: RNA_SEQ, CHIP_TF, DNASE, ATAC, CAGE, PROCAP, CHIP_HISTONE (o modalidades solo RAW_SCORES: SPLICE_SITES, SPLICE_SITE_USAGE, SPLICE_JUNCTIONS, POLYADENYLATION, CONTACT_MAPS).
• <Fuente>: Identificador de fuente de teselas del mapa de calor: ACTIVE_ISM (huellas de motivo ponderadas por actividad _TIMES_ACTIVE y logotipos de secuencia CWM), RAW_SCORES (pistas de puntuación de variante ISM sin procesar, que también renderizan huellas de motivo ISM sin procesar y logotipos de secuencia CWM en todas las modalidades), o REF_SCORES (gráficos de línea de señal de referencia continua sin letras de secuencia ni motivos). Las pistas calibradas y AVI no se pueden anclar, y los sufijos heredados :heatmap:...:<TilesetId> fallan en la búsqueda de pistas y se ignoran.

Receta para la visualización automática de motivos al cargar

1. Agregue entradas de la forma pinned:<NombreMetadatosPista>:<NúmeroCadena>:<NombreCortoScorer>:<Fuente> (usando ACTIVE_ISM para motivos ponderados por actividad o RAW_SCORES para motivos ISM sin procesar) directamente a lItems solo para las pistas objetivo específicas.
2. Establezca el intervalo de viewport i a resolución de par de bases ($\ge 2\text{ px/bp}$, ventana $\le 380\text{ bp}$).
3. Configure f con la línea celular y los factores de transcripción.

---

5. Predicciones de pista y comparaciones Ref vs. Alt (/atlas/track-predictions)

La página dedicada /atlas/track-predictions compara los perfiles funcionales predichos entre los alelos de Referencia y Alternativos para puntuaciones seleccionadas en ventanas genómicas:

• Ruta: https://deepmind.google.com/science/alphagenome/atlas/track-predictions
• Visualizaciones: Gráficos de línea expandidos (expresión, accesibilidad de la cromatina, unión de TF) y gráficos de arco Sashimi (uniones de empalme).

Generación automatizada de enlaces de predicción (scripts/alphagenome_atlas_links.py track-predictions)

Construya siempre las URL de predicción de pista usando scripts/alphagenome_atlas_links.py track-predictions. El formateo manual de la cadena ScoreId es propenso a errores debido a las coordenadas de omisión de donante/aceptador, la orientación de la cadena (+/-) y las reglas de sufijo génico vs. no génico. El script maneja automáticamente la extracción de coordenadas de GENCODE v46, la resolución del catálogo de pistas y la síntesis de URL.

# Variante y 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

# Consulta de intervalo/locus:
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

Opciones CLI compatibles para track-predictions

• --variant, -v (string, predeterminado: None): Cadena de variante en formato chr:pos_1_based:ref>alt.
• --gene, -g (string, predeterminado: None): Símbolo del gen objetivo (limita el viewport i= y calcula las uniones de empalme).
• --gene_id (string, predeterminado: None): ID del gen Ensembl objetivo (ej. ENSG00000092529.26).
• --interval, -i (string, predeterminado: None): Intervalo genómico del viewport en formato chr:inicio-fin.
• --biosample, -b (string, predeterminado: Muscle_Skeletal): Muestra biológica o consulta de tejido objetivo (ej. Muscle_Skeletal, K562, Whole_Blood).
• --modalities, -m (string, predeterminado: SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF): Lista separada por comas de modalidades (SPLICE_JUNCTIONS, RNA_SEQ, DNASE, ATAC, CHIP_TF).
• --tf (string, predeterminado: CTCF): Nombre del factor de transcripción para pistas ChIP-TF (ej. CTCF, GATA1).
• --rename (string, predeterminado: None): Anulaciones de cambio de nombre de pista personalizadas en la tarjeta gráfica.
• --legend_title (string, predeterminado: None): Encabezado de leyenda personalizado para la tarjeta gráfica.
• --format (enum, predeterminado: table): Formato de salida (table, url, json).

[!IMPORTANT] Regla de co-trazado obligatorio de empalme y RNA-seq: Al generar enlaces profundos /atlas/track-predictions, trazar o visualizar datos de impacto de variantes para variantes de empalme, trace siempre la expresión continua de RNA-seq junto con las pistas de empalme (SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, SPLICE_SITES). Las mutaciones de empalme activan con frecuencia uniones de empalme crípticas y desencadenan la degradación mediada por codones sin sentido (NMD) o alteran la salida total de transcritos; evaluar las uniones de empalme (arcos sashimi) junto con la cobertura de lectura continua de RNA-seq es necesario para observar tanto el defecto estructural del empalme como el cambio resultante en la abundancia general de transcritos.

[!IMPORTANT] Proporcione siempre i= acotado en las URL de predicción de pista: Omitir scores= o dejar el intervalo genómico (i=) sin acotar hace que la aplicación web intente consultar todas las pistas coincidentes en el locus más amplio, lo que provoca una latencia severa o que la página se congele. alphagenome_atlas_links.py track-predictions acota automáticamente i= al gen objetivo o al intervalo solicitado.

---

[!IMPORTANT] Regla de co-trazado obligatorio de empalme y RNA-seq: Al generar enlaces profundos /atlas/track-predictions, trazar o visualizar datos de impacto de variantes para variantes de empalme, trace siempre la expresión continua de RNA-seq junto con las pistas de empalme (SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, SPLICE_SITES). Las mutaciones de empalme activan con frecuencia uniones de empalme crípticas y desencadenan la degradación mediada por codones sin sentido (NMD) o alteran la salida total de transcritos; evaluar las uniones de empalme (arcos sashimi) junto con la cobertura de lectura continua de RNA-seq es necesario para observar tanto el defecto estructural del empalme como el cambio resultante en la abundancia general de transcritos.

[!IMPORTANT] Proporcione siempre i= acotado en las URL de predicción de pista: Omitir scores= o dejar el intervalo genómico (i=) sin acotar hace que la aplicación web intente consultar todas las pistas coincidentes en el locus más amplio, lo que provoca una latencia severa o que la página se congele. alphagenome_atlas_links.py track-predictions acota automáticamente i= al gen objetivo o al intervalo solicitado.

---

[!IMPORTANT] Regla de co-trazado obligatorio de empalme y RNA-seq: Al generar enlaces profundos /atlas/track-predictions, trazar o visualizar datos de impacto de variantes para variantes de empalme, trace siempre la expresión continua de RNA-seq junto con las pistas de empalme (SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, SPLICE_SITES). Las mutaciones de empalme activan con frecuencia uniones de empalme crípticas y desencadenan la degradación mediada por codones sin sentido (NMD) o alteran la salida total de transcritos; evaluar las uniones de empalme (arcos sashimi) junto con la cobertura de lectura continua de RNA-seq es necesario para observar tanto el defecto estructural del empalme como el cambio resultante en la abundancia general de transcritos.

[!IMPORTANT] Proporcione siempre i= acotado en las URL de predicción de pista: Omitir scores= o dejar el intervalo genómico (i=) sin acotar hace que la aplicación web intente consultar todas las pistas coincidentes en el locus más amplio, lo que provoca una latencia severa o que la página se congele. alphagenome_atlas_links.py track-predictions acota automáticamente i= al gen objetivo o al intervalo solicitado.