jepa-spillover

<div align="center">

JEPA-Spillover

Aprendizado preditivo em espaço latente para vigilância genômica de vírus com potencial zoonótico

Uma abordagem baseada em redes JEPA (Joint Embedding Predictive Architecture)

Subprojeto de Pós-Doutorado Júnior — PDJ/Fiocruz · Instituto Aggeu Magalhães — Fiocruz Pernambuco

</div>

---

Visão geral

Eventos de transbordamento zoonótico (spillover) estão entre as maiores ameaças à saúde pública global. O volume de genomas virais cresce rapidamente (vigilância genômica, metagenômica ambiental, estudos de viroma), mas a maioria dos vírus recém-identificados não possui rótulos confiáveis de risco zoonótico, o que limita métodos supervisionados tradicionais.

Este projeto desenvolve uma abordagem auto-supervisionada baseada em redes JEPA para aprender representações latentes de genomas virais, hospedeiros e contextos ecológicos, com o objetivo de priorizar vírus com maior potencial de spillover antes da ocorrência de surtos.

Em vez de reconstruir nucleotídeos ou depender exclusivamente de rótulos escassos, a JEPA aprende a prever embeddings de regiões genômicas (e de hospedeiros compatíveis) em um espaço latente compartilhado — capturando relações funcionais e estruturais úteis para inferir risco zoonótico.

Por que JEPA?

Objetivos

Geral: desenvolver uma abordagem JEPA para aprender representações latentes de genomas virais, hospedeiros e contextos ecológicos, apoiando a predição e priorização de vírus com potencial de spillover.

Específicos (resumo): coletar e curar genomas virais públicos; integrar metadados de hospedeiros, taxonomia e ecologia; construir representações (k-mers, embeddings Transformer); implementar a JEPA genômica e sua extensão vírus-hospedeiro/multimodal; avaliar embeddings (UMAP/t-SNE, clustering, vizinhança latente); fazer fine-tuning supervisionado para risco de spillover; comparar com baselines (k-mers, LSTM, Transformer supervisionado); aplicar interpretabilidade e ablação; e disponibilizar tudo em repositório público reprodutível.

Arquitetura do pipeline

flowchart LR
    A[Bases públicas<br/>NCBI Virus · VirusHostDB<br/>VirHostNet · GBIF/WAHIS] --> B[Coleta<br/>scripts/download_*]
    B --> C[Curadoria<br/>dedup · QC · taxonomia]
    C --> D[Representações<br/>k-mers · embeddings]
    D --> E[JEPA genômica<br/>contexto → alvo latente]
    E --> F[Extensão<br/>vírus-hospedeiro / multimodal]
    F --> G[Fine-tuning<br/>risco de spillover]
    G --> H[Avaliação · baselines<br/>UMAP/t-SNE · SHAP]
    H --> I[Ranking de vírus<br/>prioritários]
    I --> J[Dashboard · relatório<br/>GitHub · Hugging Face]

Diagramas detalhados (arquitetura JEPA, fluxo de dados, governança) estão em docs/flowcharts/ e docs/architecture.md.

Estrutura do repositório

.
├── config/                 # Configuração central (config.yaml)
├── data/                   # raw / interim / processed / external (não versionados)
├── docs/                   # Documentação técnica + fluxogramas (Mermaid)
├── presentations/          # Slides (Marp/Markdown)
├── scripts/                # Download de bases + execução do pipeline + push git/HF
├── src/jepa_spillover/     # Pacote Python (pipeline, modelos, avaliação)
│   ├── data/               # download, curate, kmers
│   ├── features/           # embeddings
│   ├── models/             # jepa_genomic, jepa_host, baselines
│   ├── training/           # treino JEPA e fine-tuning
│   ├── evaluation/         # métricas, comparação, ranking
│   └── viz/                # UMAP/t-SNE, espaço latente
├── dashboard/              # App Streamlit (embeddings + ranking)
├── notebooks/              # Exploração e análises
├── results/                # checkpoints, figuras, métricas, rankings
└── tests/                  # Testes

Instalação rápida

# Opção A — Conda (recomendado; inclui ferramentas de bioinformática)
make setup
conda activate jepa-spillover

# Opção B — pip
python -m venv .venv && source .venv/bin/activate
make setup-pip

Uso

# 1) Baixar as bases públicas (configure seu e-mail do NCBI em config/config.yaml)
make download

# 2) Pipeline completo de ponta a ponta
make pipeline

# Ou passo a passo:
make curate      # curadoria e padronização
make features    # k-mers + embeddings
make train       # pré-treino JEPA genômica
make finetune    # fine-tuning supervisionado (risco de spillover)
make evaluate    # métricas, baselines, UMAP/t-SNE, ranking

# 3) Explorar resultados no dashboard
make dashboard

Cada subcomando também está disponível via CLI:

python -m jepa_spillover.cli --help

Fontes de dados

Detalhes, termos de uso e citações em docs/data_sources.md. GISAID exige credenciamento e não é redistribuído por este repositório.

Metas e entregáveis (12 meses)

Cronograma completo em docs/roadmap.md.

Reprodutibilidade e ciência aberta

• Configuração única e versionada (config/config.yaml) e seed fixa.
• Ambiente declarado (environment.yml / requirements.txt).
• Acompanhamento de experimentos com Trackio.
• Código, modelos e documentação publicados em GitHub e Hugging Face Hub, respeitando normas institucionais de sigilo e propriedade intelectual.

Aviso

Ferramenta de apoio à priorização para vigilância, em estágio de prova de conceito. Não substitui investigação laboratorial nem decisões de saúde pública. Resultados in silico exigem validação experimental.

Como citar

@software{camara_jepa_spillover_2026,
  author  = {Câmara, Gabriel Bezerra Motta},
  title   = {JEPA-Spillover: aprendizado preditivo em espaço latente para
             vigilância genômica de vírus com potencial zoonótico},
  year    = {2026},
  note    = {Instituto Aggeu Magalhães — Fiocruz Pernambuco},
  url     = {https://github.com/gbmotta/jepa-spillover}
}

Licença

Código sob licença MIT. Dados de terceiros mantêm as licenças e termos de uso de suas fontes originais.

---

<div align="center"> Instituto Aggeu Magalhães · Fiocruz Pernambuco · PDJ/Fiocruz · 2026 </div>