geniml

Essa habilidade deve ser usada ao trabalhar com dados de intervalos genômicos (arquivos BED) para tarefas de machine learning. Use para treinar embeddings de regiões (Region2Vec, BEDspace), análise de

SKILL.md

GitHub

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

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):

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