google-deepmind/science-skills

Análise de Variantes usando AlphaGenome

Pré-requisitos

1. uv: Leia a skill uv e siga as instruções de Configuração para garantir que uv esteja instalado e no PATH.

2. Notificação ao Usuário: Se .licenses/alphagenome_single_variant_analysis_LICENSE.txt já não existir no diretório raiz do workspace, então (1) notifique proeminentemente o usuário para verificar os termos em https://deepmind.google.com/science/alphagenome/, depois (2) crie o arquivo registrando o texto da notificação e o timestamp.

3. Arquivo .env: Certifique-se de que o arquivo .env existe no seu diretório home. Crie um se ele não existir.

4. ALPHAGENOME_API_KEY: Esta skill requer uma chave de API para funcionar.

   Você pode se registrar para obter uma chave em https://deepmind.google.com/science/alphagenome/. Você DEVE usar o protocolo seguro de credenciais na skill credentials para verificar e solicitar esta chave se esta skill parecer relevante para a solicitação do usuário.

5. ALPHAGENOME_GTF_PATH (Opcional): Acelere a busca de genes/transcrições apontando para uma cópia local do arquivo feather GTF em vez de baixar do GCS:

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

Regras Principais

• NUNCA execute python3 ou python3 -c diretamente. O Python do sistema não necessariamente tem pandas, numpy e outras dependências chave. SEMPRE use uv run para executar TODO código Python — incluindo scripts, arquivos de análise ad-hoc e one-liners. Não tente pip install ou criar novos ambientes virtuais — uv gerencia um ambiente isolado automaticamente.
• Apenas Offline: NUNCA use APIs externas (ex.: MyGene.info, Ensembl REST) para busca de genes/transcrições. Use lookup_gene_info.py com o GTF local. Se falhar, corrija o ambiente/caminhos, não mude para APIs externas.
• Chave de API é obrigatória: ALPHAGENOME_API_KEY deve estar definida antes de executar qualquer script.
• Notificação: Se esta skill for usada, garanta que isso seja mencionado na saída.
• Formato do Relatório: Sempre use os templates em docs/report-templates.md para gerar relatórios de análise, e garanta incluir a tabela dos principais resultados da varredura de descoberta.

Configuração do Ambiente & Solução de Problemas

Ambiente Python

Todos os scripts devem ser executados usando uv run, que gerencia um ambiente virtual isolado com as dependências corretas via uv.

uv run <nome_do_script> [args...]

Para scripts ad-hoc (ex.: código de análise inline salvo em um arquivo temporário), passe o caminho completo em vez de um nome curto:

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

[!NOTE] A primeira invocação resolve e instala as dependências (~10s). Execuções subsequentes usam o ambiente em cache e iniciam instantaneamente. O cache fica em ~/.cache/uv/.

Problemas Comuns

• Nomes de Colunas: tidy_scores e metadados frequentemente usam gene_name (não gene_symbol) e output_type (não modality). Sempre inspecione df.columns antes de filtrar.
• Genes Grandes: Genes > 500kb (ex.: USH2A) quebram a visão whole_gene. Use --view detail ou janelas regionais manuais.
• Erro de Strand no Sashimi: plot_components.Sashimi NÃO aceita um argumento strand diretamente. Filtre as tracks de entrada.
• KeyError: 'ontology_curie': Nem todas as tracks têm ontology_curie. Verifique track.metadata.columns antes de filtrar.
• Python Path: Se ocorrer exec: "python": executable file not found, certifique-se de estar usando uv run em vez de python/python3 puro.
• NotImplementedError (pandas): "iLocation based boolean indexing on an integer type is not available". Isso ocorre ao usar máscaras booleanas com .iloc em DataFrames indexados por inteiros em versões mais novas do pandas. Correção: Converta máscaras booleanas para índices inteiros usando np.flatnonzero(mask).
• Sensibilidade a Maiúsculas no GTF Feather: O arquivo Feather GTF do AlphaGenome usa nomes de colunas Capitalizados (Feature, Start, End, Strand) diferentemente de arquivos GTF padrão. Sempre verifique df.columns se ocorrerem KeyErrors.
• Filtragem de ontologia no score_variant: score_variant NÃO aceita ontology_terms como argumento. Você deve filtrar os objetos AnnData retornados manualmente inspecionando as colunas adata.var. Em contraste, predict_variant ACEITA ontology_terms diretamente.
• Lógica de Zoom do Sashimi: Para garantir que arcos de "pulo" (skipping) sejam visíveis, expanda o zoom para incluir os éxons flanqueadores em vez de confiar apenas na sobreposição de junções.
• Pontuações de Junções: Objetos Junction brutos de prediction podem ser Intervalos simples. Use junction_data.get_junctions_to_plot(predictions=..., name=...) para recuperar objetos com o atributo .k (abundância/pontuação).
• uv Não Encontrado: Se ocorrer exec: uv: not found, siga as instruções de instalação em Pré-requisitos.
• Erro de Autenticação de Registro (401): Se uv falhar com 401 Não Autorizado para um registro privado, defina UV_INDEX_URL=https://pypi.org/simple antes de executar o script.

Referências

• alphagenome-api.md — Referência da API e padrões de código
• interpretation-guide.md — Guia de interpretação, regras de magnitude de pontuação, ISM e checklist.
• report-templates.md — Modelos completos de relatório
• scripts/visualize_variant_effects.py — Modelo de visualização de variante única (comparações Ref/Alt, Splicing).
  • Estratégia de Zoom para Splicing: Usa uma Abordagem Híbrida para visibilidade ideal:
    1. Intervalo Base: Variante +/- 1 éxon a montante e a jusante (Contexto Estrutural).
    2. Expansão de Junção: Expande para incluir a extensão total de qualquer junção de splicing significativa (ex.: eventos de skipping de éxon que abrangem múltiplos éxons).
    3. Reforço de Ancoragem: Garante que os éxons ancorando essas junções longas estejam totalmente visíveis. Lição: Janelas fixas simples (ex.: 2kb) ou lógica de éxon mais próximo frequentemente falham para eventos de skipping. Sempre use os dados observados de junção para determinar os níveis de zoom.
• examples/splicing/ — Exemplos de análise de splicing
• examples/model_limitation_RNU4ATAC/ — Estudo de caso de limitação de estrutura de ncRNA
• examples/polyadenylation_HBA2/ — Estudo de caso de 3' UTR / Poliadenilação
• examples/regulatory/ — Exemplos de variantes regulatórias
• examples/negative_result_GATA4/ — Resultados negativos (artefato matemático)
• examples/negative_result_TGFB3/ — Resultados negativos (proxies)
• scripts/lookup_gene_info.py — Busca de genes & transcrições
• scripts/resolve_ontology_terms.py — Resolução de termos de ontologia (IDs UBERON/CL)

---

Padrões de Código

Varredura Ampla de Descoberta

Use score_variant com scorers diferenciais apenas para descobrir efeitos inesperados em tecidos.

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

# Carregar variáveis de ambiente de ~/.env
dotenv.load_dotenv(os.path.expanduser('~/.env'))

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

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

# Usar comprimento de sequência suportado (ex.: 2**20 para desempenho ideal)
SEQ_LENGTH = 2**20
intervalo = genome.Interval(cromossomo, pos - SEQ_LENGTH // 2, pos + SEQ_LENGTH // 2)
variante = genome.Variant(cromossomo, 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"Pontuando variante {variant_str}...")
lista_pontuacoes = dna_model.score_variant(interval=intervalo, variant=variante, variant_scorers=scorers)

# Processar e Exibir Resultados
todos_dfs = []
for score_adata in lista_pontuacoes:
    df = variant_scorers.tidy_scores([score_adata], match_gene_strand=True)
    if df is not None:
        todos_dfs.append(df)

if todos_dfs:
    df = pd.concat(todos_dfs)
    significativos = df[df['quantile_score'].abs() > 0.995]
    classificados = significativos.sort_values('raw_score', key=abs, ascending=False)
    print("Principais Resultados Significativos:")
    print(classificados[['biosample_name', 'gene_name', 'output_type', 'quantile_score', 'raw_score']])

Busca Estendida para Tecidos Relevantes a Doenças

# Definir palavras-chave baseadas no contexto da doença
palavras_chave_doenca = ["fígado", "hepatócito"]

# Filtrar para qualquer correspondência
mascara = df['biosample_name'].str.contains('|'.join(palavras_chave_doenca), case=False, na=False)

resultados_relevantes = df[mascara].sort_values('raw_score', key=abs, ascending=False)
print(f"\n--- Análise Estendida (Palavras-chave: {palavras_chave_doenca}) ---")
print(resultados_relevantes.head(20)[['biosample_name', 'output_type', 'raw_score', 'quantile_score']])

Checklist do Workflow

Progresso da Análise de Variantes:
- [ ] Passo 0: Revisar Exemplos de Ouro (OBRIGATÓRIO)
- [ ] Passo 1: Criar Pasta de Saída e Configuração
- [ ] Passo 2: Analisar Consulta do Usuário & Pesquisar
- [ ] Passo 3: Resolver Tecidos & Modalidades
- [ ] Passo 4: Visualizar & Salvar Gráficos
- [ ] Passo 5: Analisar Predições (visualizar gráficos, sem código). OBRIGATÓRIO: Ler [interpretation-guide.md](docs/interpretation-guide.md) antes de interpretar resultados.
- [ ] Passo 6: Escrever Relatório, salvar como `report.md` (OBRIGATÓRIO)
- [ ] Passo 7: Autocrítica (visualizar `report.md` para verificar links e afirmações)
- [ ] Passo 8: Criar artefato a partir de `report.md`

---

Workflow Multi-Variante

Se múltiplas variantes forem especificadas, crie subagentes para executar cada análise de variante e depois sintetize cada report.md em um único relatório.

Referência de Scripts

Script	Propósito
lookup_gene_info	Busca abrangente de genes e transcrições usando
: : dados GTF :
resolve_ontology_terms	Termos biológicos → IDs UBERON/CL/EFO
visualize_variant_effects	Visualização REF/ALT (expressão, regulação,
: : splicing) :
analyze_ism	Geração de SeqLogo de Mutagênese In Silico
interpret_splicing	Análise quantitativa de splicing (pontuações
: : delta, junções) :
visualize_genome_tracks	Visualização de tracks genômicas para uma região