deepmind/ciências-genoma

Configuração de URL e Links Profundos do Atlas AlphaGenome

Construa e valide links profundos para o aplicativo web Atlas AlphaGenome (https://deepmind.google.com/science/alphagenome/atlas).

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

[!IMPORTANT] Links Profundos Obrigatórios com Scores de Variante: Ao apresentar, discutir ou classificar variantes genéticas, você DEVE sempre fornecer links profundos clicáveis para o AlphaGenome Atlas. Use scripts/alphagenome_atlas_links.py para automatizar a geração de links e tabelas.

---

Pré-requisitos

# 1. Link de Exploração de Variante Única:
uv run scripts/alphagenome_atlas_links.py variant "chr9:128225994:G>A" \
  --biosample K562 \
  --modalities RNA_SEQ,DNASE,CHIP_TF

# 2. Link 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. Formatar Tabela de Registros de Variantes Candidatas (com links clicáveis embutidos):
uv run scripts/alphagenome_atlas_links.py table --input top_variants.json --biosample K562

# 4. Construir Link de Predições de Faixas 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 URL

• q (string, Obrigatório): Alvo de pesquisa primário. Suporta intervalos fechados 1-based (chr11:5288500-5290500), símbolos de genes (BRCA1), IDs Ensembl (ENSG00000012048) ou variantes 1-based (chr7:27170000:A>G).
• m (enum, Opcional): Modo de visualização. Padrão: entity para genes/variantes e locus para intervalos de coordenadas. Use variant para consultas de variantes. (Permitidos: locus, entity, variant, motifs).
• i (string, Opcional): Intervalo de zoom do visor centralizado no formato fechado 1-based chr:início-fim (ex.: chr11:5289310-5289690). Obrigatório para renderização automática de motivos.
• f (string, Opcional): Predicados de filtro separados por vírgula no formato CHAVE:VALOR (ex.: BIOSAMPLE_NAME:K562,SCORER_MODALITY:RNA-seq,ASSAY_TRANSCRIPTOR_FACTOR:GATA1). Controla as linhas visíveis do heatmap.
• lItems (string, Opcional): Sequência de itens de layout, alternância da faixa de score AVI (avi), heatmaps de seção e lista de faixas fixadas (ex.: avi,section:RNA_SEQ,section:DNASE,pinned:<TrackKey>).
• scores (string, Opcional): Lista separada por vírgula de tokens ScoreId para a página /atlas/track-predictions (ex.: <ScoreId1>,<ScoreId2>).
• md (enum, Opcional): Seletor de guia de modalidade ativa na visualização de predições de faixas (RNA_SEQ, SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, DNASE).
• tpRenames (string, Opcional): Substituições de título personalizadas para predições de score específicas (ScoreId:TítuloPersonalizado).
• tpLegendTitle (string, Opcional): Título personalizado da legenda para o card do gráfico de predições de faixas (ex.: Expressão Gênica Predita).

[!IMPORTANT] Formato de Consulta de Variante: Variantes em q devem usar estritamente o formato chr:posição_1_based:ref>alt (ex.: chr7:27170000:A>G ou codificado em URL chr7:27170000:A%3EG, onde a posição é 1-based). Não use alelos separados por dois-pontos (A:G) ou rsIDs do dbSNP (rsIDs não são suportados).

---

3. Filtragem Multimodal e a Armadilha do Grupo de Ensaio (f)

Grupos de Filtro e Avaliação Booleana

Filtros em f mapeiam para três grupos de avaliação primários:

• Grupo Biosample (BIOSAMPLE_NAME, BIOSAMPLE_TYPE): Avaliado com lógica E.
• Grupo Ensaio (SCORER_MODALITY, ASSAY_TRANSCRIPTOR_FACTOR, ASSAY_HISTONE_MARK): Avaliado com lógica OU.
• Grupo Gene (GENE_NAME): Avaliado com lógica OU.

⚠️ Regra de Filtro Multimodal Obrigatória

As faixas RNA-seq e DNase não têm código de fator de transcrição (transcriptionFactorCode === ""). Se f contiver apenas ASSAY_TRANSCRIPTOR_FACTOR no grupo Ensaio, as faixas RNA-seq e DNase falham na avaliação do Ensaio e são ocultadas do heatmap.

Para exibir faixas RNA-seq e DNase junto com fatores de transcrição ChIP-seq específicos, inclua explicitamente SCORER_MODALITY:RNA-seq e SCORER_MODALITY:DNase em f (manipulado automaticamente 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. Configuração de Layout, Scores AVI e Faixas Fixadas (lItems)

Plotando Scores de Impacto de Variante AVI e Seções de Modalidade

• Faixa de Impacto de Variante AVI (avi): Incluir avi em lItems renderiza a faixa de score de Impacto de Variante AlphaGenome de nível superior para o intervalo ou variante.
• Seções de Modalidade de Banco de Dados (section:<MODALIDADE>): Seções renderizam heatmaps completos não fixados em todas as faixas correspondentes para aquela modalidade (ex.: section:RNA_SEQ, section:DNASE, section:CHIP_TF, section:ATAC, section:CAGE).

Faixas Fixadas e Instâncias de Motivos

[!NOTE] Diretriz de Motivo Específico da Faixa: Faixas fixadas Active-ISM com instâncias de motivos e logotipos de Matriz de Peso de Contribuição (CWM) devem ser adicionadas apenas quando solicitadas especificamente para faixas individuais. Apenas um subconjunto limitado de faixas (como faixas ChIP-TF ou RNA-seq chave relevantes para o locus) suporta e se beneficia de sobreposições de motivos fixados. Para links de exploração padrão, heatmaps de seção padrão (avi,section:RNA_SEQ,section:DNASE,section:CHIP_TF) sem faixas fixadas são preferidos.

Instâncias de motivos e logotipos CWM são renderizados exclusivamente em faixas de sequência fixadas (ACTIVE_ISM ou RAW_SCORES, não REF_SCORES) em resolução de pares de base. Heatmaps de seção geral não acionam a renderização de pegadas de motivos.

Esquema de Chave de Faixa Fixada

pinned:<NomeMetadadosFaixa>:<NúmeroStrand>:<NomeReduzidoScorer>:<Fonte>

Exemplo de entrada lItems em uma string de consulta URL bruta:

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

• <NomeMetadadosFaixa>: Nome exato da faixa do proto de metadados (ex.: EFO:0002067 TF ChIP-seq GATA1), codificado em percentagem (%20 para espaços) em strings de consulta URL brutas (ou não codificado quando passado através de urllib.parse.urlencode).
• <NúmeroStrand>: 1 (STRAND_POSITIVE), 2 (STRAND_NEGATIVE), 3 (STRAND_UNSTRANDED).
• <NomeReduzidoScorer>: RNA_SEQ, CHIP_TF, DNASE, ATAC, CAGE, PROCAP, CHIP_HISTONE (ou modalidades RAW_SCORES: SPLICE_SITES, SPLICE_SITE_USAGE, SPLICE_JUNCTIONS, POLYADENYLATION, CONTACT_MAPS).
• <Fonte>: Identificador de fonte do conjunto de tiles do heatmap: ACTIVE_ISM (pegadas de motivo _TIMES_ACTIVE ponderadas por atividade e logotipos de sequência CWM), RAW_SCORES (faixas de score de variante ISM brutas, também renderizando pegadas de motivo ISM brutas e logotipos de sequência CWM em todas as modalidades) ou REF_SCORES (gráficos de linha de sinal de referência contínua sem letras de sequência ou motivos). Faixas calibradas e AVI não podem ser fixadas, e sufixos legados :heatmap:...:<TilesetId> falham na pesquisa de faixas e são ignorados.

Receita para Exibição Automática de Motivos ao Carregar

1. Anexe entradas no formato pinned:<NomeMetadadosFaixa>:<NúmeroStrand>:<NomeReduzidoScorer>:<Fonte> (usando ACTIVE_ISM para motivos ponderados por atividade ou RAW_SCORES para motivos ISM brutos) diretamente a lItems apenas para as faixas alvo específicas.
2. Defina o intervalo do visor i para resolução de pares de base ($\ge 2\text{ px/bp}$, janela $\le 380\text{ bp}$).
3. Configure f com linhagem celular e fatores de transcrição.

---

5. Predições de Faixas e Comparações Ref vs. Alt (/atlas/track-predictions)

A página dedicada /atlas/track-predictions compara perfis funcionais preditos entre os alelos de Referência e Alternativo para scores selecionados em janelas genômicas:

• Rota: https://deepmind.google.com/science/alphagenome/atlas/track-predictions
• Visualizações: Gráficos de linha expandidos (expressão, acessibilidade da cromatina, ligação de TF) e gráficos de arco Sashimi (junções de splicing).

Geração Automatizada de Link de Predição (scripts/alphagenome_atlas_links.py track-predictions)

Sempre construa URLs de predição de faixa usando scripts/alphagenome_atlas_links.py track-predictions. A formatação manual de string ScoreId é propensa a erros devido a coordenadas de skipping de doador/aceitador, orientação da fita (+/-) e regras de sufixo gênico vs. não gênico. O script lida automaticamente com a extração de coordenadas do GENCODE v46, resolução do catálogo de faixas e síntese de URL.

# Variante & Gene:
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

Opções de CLI Suportadas para track-predictions

• --variant, -v (string, padrão: None): String de variante no formato chr:posição_1_based:ref>alt.
• --gene, -g (string, padrão: None): Símbolo do gene alvo (limita o visor i= e calcula junções de splicing).
• --gene_id (string, padrão: None): ID do gene Ensembl alvo (ex.: ENSG00000092529.26).
• --interval, -i (string, padrão: None): Intervalo genômico do visor no formato chr:início-fim.
• --biosample, -b (string, padrão: Muscle_Skeletal): Bioamostra ou tecido alvo (ex.: Muscle_Skeletal, K562, Whole_Blood).
• --modalities, -m (string, padrão: SPLICE_JUNCTIONS,RNA_SEQ,DNASE,CHIP_TF): Lista separada por vírgula de modalidades (SPLICE_JUNCTIONS, RNA_SEQ, DNASE, ATAC, CHIP_TF).
• --tf (string, padrão: CTCF): Nome do fator de transcrição para faixas ChIP-TF (ex.: CTCF, GATA1).
• --rename (string, padrão: None): Substituições de renomeação personalizadas de faixa no card do gráfico.
• --legend_title (string, padrão: None): Cabeçalho personalizado da legenda para o card do gráfico.
• --format (enum, padrão: table): Formato de saída (table, url, json).

[!IMPORTANT] Regra Obrigatória de Co-plotagem de Splicing e RNA-seq: Ao gerar links profundos /atlas/track-predictions, plotar ou visualizar dados de impacto de variante para variantes de splicing, sempre plote expressão RNA-seq contínua junto com faixas de splicing (SPLICE_JUNCTIONS, SPLICE_SITE_USAGE, SPLICE_SITES). Mutações de splicing frequentemente ativam junções de splicing crípticas e desencadeiam decaimento mediado por mutação nonsense (NMD) ou alteram a saída total do transcrito; avaliar junções de splicing (arcos sashimi) juntamente com a cobertura de leitura RNA-seq contínua é necessário para observar tanto o defeito estrutural do splicing quanto a mudança resultante na abundância geral do transcrito.

[!IMPORTANT] Sempre Forneça i= Limitado em URLs de Predição de Faixa: Omitir scores= ou deixar o intervalo genômico (i=) sem limites faz com que o aplicativo web tente consultar todas as faixas correspondentes em todo o locus mais amplo, levando a latência severa ou travamento da página. alphagenome_atlas_links.py track-predictions limita automaticamente i= ao gene alvo ou intervalo solicitado.