Geniml

Geniml: Machine Learning em Intervalos Genômicos

Visão Geral

Geniml é um pacote Python para construir modelos de machine learning em dados de intervalos genômicos de arquivos BED. Ele fornece métodos não supervisionados para aprender embeddings de regiões genômicas, células únicas e rótulos de metadados, habilitando buscas por similaridade, agrupamento e tarefas de ML subsequentes.

Instalação

Instale geniml usando uv:

uv uv pip install geniml

Para dependências de ML (PyTorch, etc.):

uv uv pip install 'geniml[ml]'

Versão de desenvolvimento do GitHub:

uv uv pip install git+https://github.com/databio/geniml.git

Capacidades Principais

Geniml fornece cinco capacidades primárias, cada uma detalhada em arquivos de referência dedicados:

1. Region2Vec: Embeddings de Regiões Genômicas

Treine embeddings não supervisionados de regiões genômicas usando aprendizado estilo word2vec.

Use para: Redução de dimensionalidade de arquivos BED, análise de similaridade de regiões, vetores de recursos para ML subsequente.

Workflow:

1. Tokenize arquivos BED usando uma referência de universo
2. Treine o modelo Region2Vec nos tokens
3. Gere embeddings para regiões

Referência: Veja references/region2vec.md para workflow detalhado, parâmetros e exemplos.

2. BEDspace: Embeddings Conjuntos de Regiões e Metadados

Treine embeddings compartilhados para conjuntos de regiões e rótulos de metadados usando StarSpace.

Use para: Buscas conscientes de metadados, consultas entre modalidades (região→rótulo ou rótulo→região), análise conjunta de conteúdo genômico e condições experimentais.

Workflow:

1. Pré-processe regiões e metadados
2. Treine o modelo BEDspace
3. Calcule distâncias
4. Faça consultas entre regiões e rótulos

Referência: Veja references/bedspace.md para workflow detalhado, tipos de busca e exemplos.

3. scEmbed: Embeddings de Acessibilidade de Cromatina de Célula Única

Treine modelos Region2Vec em dados scATAC-seq para embeddings em nível de célula.

Use para: Agrupamento de scATAC-seq, anotação de tipo de célula, redução de dimensionalidade de células únicas, integração com workflows scanpy.

Workflow:

1. Prepare AnnData com coordenadas de picos
2. Pré-tokenize células
3. Treine o modelo scEmbed
4. Gere embeddings de células
5. Agrupe e visualize com scanpy

Referência: Veja references/scembed.md para workflow detalhado, parâmetros e exemplos.

4. Picos Consensuais: Construção de Universos

Construa conjuntos de picos de referência (universos) a partir de coleções de arquivos BED usando múltiplos métodos estatísticos.

Use para: Criar referências de tokenização, padronizar regiões entre conjuntos de dados, definir recursos consensuais com rigor estatístico.

Workflow:

1. Combine arquivos BED
2. Gere pistas de cobertura
3. Construa universo usando método CC, CCF, ML ou HMM

Métodos:

• CC (Corte de Cobertura): Baseado em limiar simples
• CCF (Corte de Cobertura Flexível): Intervalos de confiança para limites
• ML (Máxima Verossimilhança): Modelagem probabilística de posições
• HMM (Modelo de Markov Oculto): Modelagem complexa de estados

Referência: Veja references/consensus_peaks.md para comparação de métodos, parâmetros e exemplos.

5. Utilitários: Ferramentas de Suporte

Ferramentas adicionais para cache, aleatorização, avaliação e busca.

Utilitários disponíveis:

• BBClient: Cache de arquivos BED para acesso repetido
• BEDshift: Aleatorização preservando contexto genômico
• Evaluation: Métricas para qualidade de embeddings (silhueta, Davies-Bouldin, etc.)
• Tokenization: Utilitários de tokenização de regiões (hard, soft, baseada em universo)
• Text2BedNN: Backends de busca neural para consultas genômicas

Referência: Veja references/utilities.md para uso detalhado de cada utilitário.

Workflows Comuns

Pipeline Básico de Embedding de Regiões

from geniml.tokenization import hard_tokenization
from geniml.region2vec import region2vec
from geniml.evaluation import evaluate_embeddings

# Passo 1: Tokenize arquivos BED
hard_tokenization(
    src_folder='bed_files/',
    dst_folder='tokens/',
    universe_file='universe.bed',
    p_value_threshold=1e-9
)

# Passo 2: Treine Region2Vec
region2vec(
    token_folder='tokens/',
    save_dir='model/',
    num_shufflings=1000,
    embedding_dim=100
)

# Passo 3: Avalie
metrics = evaluate_embeddings(
    embeddings_file='model/embeddings.npy',
    labels_file='metadata.csv'
)

Pipeline de Análise de scATAC-seq

import scanpy as sc
from geniml.scembed import ScEmbed
from geniml.io import tokenize_cells

# Passo 1: Carregue dados
adata = sc.read_h5ad('scatac_data.h5ad')

# Passo 2: Tokenize células
tokenize_cells(
    adata='scatac_data.h5ad',
    universe_file='universe.bed',
    output='tokens.parquet'
)

# Passo 3: Treine scEmbed
model = ScEmbed(embedding_dim=100)
model.train(dataset='tokens.parquet', epochs=100)

# Passo 4: Gere embeddings
embeddings = model.encode(adata)
adata.obsm['scembed_X'] = embeddings

# Passo 5: Agrupe com scanpy
sc.pp.neighbors(adata, use_rep='scembed_X')
sc.tl.leiden(adata)
sc.tl.umap(adata)

Construção de Universo e Avaliação

# Gere cobertura
cat bed_files/*.bed > combined.bed
uniwig -m 25 combined.bed chrom.sizes coverage/

# Construa universo com corte de cobertura
geniml universe build cc \
  --coverage-folder coverage/ \
  --output-file universe.bed \
  --cutoff 5 \
  --merge 100 \
  --filter-size 50

# Avalie qualidade do universo
geniml universe evaluate \
  --universe universe.bed \
  --coverage-folder coverage/ \
  --bed-folder bed_files/

Referência de CLI

Geniml fornece interfaces de linha de comando para operações principais:

# Treinamento de Region2Vec
geniml region2vec --token-folder tokens/ --save-dir model/ --num-shuffle 1000

# Pré-processamento de BEDspace
geniml bedspace preprocess --input regions/ --metadata labels.csv --universe universe.bed

# Treinamento de BEDspace
geniml bedspace train --input preprocessed.txt --output model/ --dim 100

# Busca em BEDspace
geniml bedspace search -t r2l -d distances.pkl -q query.bed -n 10

# Construção de universo
geniml universe build cc --coverage-folder coverage/ --output universe.bed --cutoff 5

# Aleatorização com BEDshift
geniml bedshift --input peaks.bed --genome hg38 --preserve-chrom --iterations 100

Quando Usar Qual Ferramenta

Use Region2Vec quando:

• Trabalhar com dados genômicos em volume (ChIP-seq, ATAC-seq, etc.)
• Precisar de embeddings não supervisionados sem metadados
• Comparar conjuntos de regiões entre experimentos
• Construir recursos para aprendizado supervisionado subsequente

Use BEDspace quando:

• Metadados disponíveis (tipos de célula, tecidos, condições)
• Precisar fazer consultas de regiões por metadados ou vice-versa
• Desejar espaço de embedding conjunta para regiões e rótulos
• Construir bancos de dados genômicos pesquisáveis

Use scEmbed quando:

• Analisar dados de scATAC-seq de célula única
• Agrupar células por acessibilidade de cromatina
• Anotar tipos de célula a partir de scATAC-seq
• Integração com scanpy é desejada

Use Construção de Universo quando:

• Precisar de conjuntos de picos de referência para tokenização
• Combinar múltiplos experimentos em consenso
• Desejar definições de regiões rigorosas estatisticamente
• Construir referências padrão para um projeto

Use Utilitários quando:

• Precisar fazer cache de arquivos BED remotos (BBClient)
• Gerar modelos nulos para estatísticas (BEDshift)
• Avaliar qualidade de embeddings (Evaluation)
• Construir interfaces de busca (Text2BedNN)

Melhores Práticas

Diretrizes Gerais

• Qualidade do universo é crítica: Invista tempo na construção de universos abrangentes e bem construídos
• Validação de tokenização: Verifique cobertura (>80% é ideal) antes de treinar
• Ajuste de parâmetros: Experimente dimensões de embedding, taxas de aprendizado e épocas de treinamento
• Avaliação: Sempre valide embeddings com múltiplas métricas e visualizações
• Documentação: Registre parâmetros e seeds aleatórias para reprodutibilidade

Considerações de Desempenho

• Pré-tokenização: Para scEmbed, sempre pré-tokenize células para treinamento mais rápido
• Gerenciamento de memória: Conjuntos de dados grandes podem exigir processamento em lotes ou downsampling
• Recursos computacionais: Métodos ML/HMM de universo são computacionalmente intensivos
• Cache de modelo: Use BBClient para evitar downloads repetidos

Padrões de Integração

• Com scanpy: Embeddings de scEmbed se integram perfeitamente como entradas adata.obsm
• Com BEDbase: Use BBClient para acessar repositórios BED remotos
• Com Hugging Face: Exporte modelos treinados para compartilhamento e reprodutibilidade
• Com R: Use reticulate para integração R (veja referência de utilitários)

Projetos Relacionados

Geniml faz parte do ecossistema BEDbase:

• BEDbase: Plataforma unificada para regiões genômicas
• BEDboss: Pipeline de processamento para arquivos BED
• Gtars: Ferramentas e utilitários genômicos
• BBClient: Cliente para repositórios BEDbase

Recursos Adicionais

• Documentação: https://docs.bedbase.org/geniml/
• GitHub: https://github.com/databio/geniml
• Modelos pré-treinados: Disponíveis no Hugging Face (organização databio)
• Publicações: Citadas na documentação para detalhes metodológicos

Solução de Problemas

"Cobertura de tokenização muito baixa":

• Verifique qualidade e completude do universo
• Ajuste limiar de p-value (tente 1e-6 em vez de 1e-9)
• Garanta que universo corresponda à montagem do genoma

"Treinamento não convergindo":

• Ajuste taxa de aprendizado (tente intervalo 0.01-0.05)
• Aumente épocas de treinamento
• Verifique qualidade de dados e pré-processamento

"Erros de falta de memória":

• Reduza tamanho de lote para scEmbed
• Processe dados em chunques
• Use pré-tokenização para dados de célula única

"StarSpace não encontrado" (BEDspace):

• Instale StarSpace separadamente: https://github.com/facebookresearch/StarSpace
• Defina parâmetro --path-to-starspace corretamente

Para solução de problemas detalhada e questões específicas do método, consulte o arquivo de referência apropriado.