Gtars

Gtars: Ferramentas e Algoritmos Genômicos em Rust

Visão Geral

Gtars é um toolkit Rust de alta performance para manipular, analisar e processar dados de intervalos genômicos. Oferece ferramentas especializadas para detecção de sobreposições, análise de cobertura, tokenização para aprendizado de máquina e gerenciamento de sequências de referência.

Use esta skill ao trabalhar com:

• Arquivos de intervalos genômicos (formato BED)
• Detecção de sobreposições entre regiões genômicas
• Geração de tracks de cobertura (WIG, BigWig)
• Pré-processamento e tokenização de ML genômica
• Análise de fragmentos em genômica de célula única
• Recuperação e validação de sequência de referência

Instalação

Instalação Python

Instale os bindings Python do gtars:

uv pip install gtars

Instalação CLI

Instale as ferramentas de linha de comando (requer Rust/Cargo):

# Instalar com todos os recursos
cargo install gtars-cli --features "uniwig overlaprs igd bbcache scoring fragsplit"

# Ou instalar recursos específicos apenas
cargo install gtars-cli --features "uniwig overlaprs"

Biblioteca Rust

Adicione ao Cargo.toml para projetos Rust:

[dependencies]
gtars = { version = "0.1", features = ["tokenizers", "overlaprs"] }

Capacidades Principais

Gtars é organizado em módulos especializados, cada um focado em tarefas específicas de análise genômica:

1. Detecção de Sobreposições e Indexação IGD

Detecte eficientemente sobreposições entre intervalos genômicos usando a estrutura de dados Integrated Genome Database (IGD).

Quando usar:

• Encontrar elementos reguladores sobrepostos
• Anotação de variantes
• Comparar picos de ChIP-seq
• Identificar características genômicas compartilhadas

Exemplo rápido:

import gtars

# Construir índice IGD e consultar sobreposições
igd = gtars.igd.build_index("regions.bed")
overlaps = igd.query("chr1", 1000, 2000)

Veja references/overlap.md para documentação abrangente de detecção de sobreposições.

2. Geração de Track de Cobertura

Gere tracks de cobertura a partir de dados de sequenciamento com o módulo uniwig.

Quando usar:

• Perfis de acessibilidade ATAC-seq
• Visualização de cobertura ChIP-seq
• Cobertura de leitura RNA-seq
• Análise de cobertura diferencial

Exemplo rápido:

# Gerar track de cobertura BigWig
gtars uniwig generate --input fragments.bed --output coverage.bw --format bigwig

Veja references/coverage.md para workflows detalhados de análise de cobertura.

3. Tokenização Genômica

Converta regiões genômicas em tokens discretos para aplicações de aprendizado de máquina, particularmente para modelos de deep learning em dados genômicos.

Quando usar:

• Pré-processamento para modelos de ML genômica
• Integração com biblioteca geniml
• Criação de codificações de posição
• Treinamento de modelos transformer em sequências genômicas

Exemplo rápido:

from gtars.tokenizers import TreeTokenizer

tokenizer = TreeTokenizer.from_bed_file("training_regions.bed")
token = tokenizer.tokenize("chr1", 1000, 2000)

Veja references/tokenizers.md para documentação de tokenização.

4. Gerenciamento de Sequência de Referência

Gerencie sequências de genoma de referência e calcule digests seguindo o protocolo GA4GH refget.

Quando usar:

• Validar integridade do genoma de referência
• Extrair sequências genômicas específicas
• Calcular digests de sequência
• Comparações entre referências

Exemplo rápido:

# Carregar referência e extrair sequências
store = gtars.RefgetStore.from_fasta("hg38.fa")
sequence = store.get_subsequence("chr1", 1000, 2000)

Veja references/refget.md para operações de sequência de referência.

5. Processamento de Fragmentos

Divida e analise arquivos de fragmentos, particularmente útil para dados de genômica de célula única.

Quando usar:

• Processar dados de ATAC-seq de célula única
• Dividir fragmentos por códigos de barras de célula
• Análise de fragmentos baseada em cluster
• Controle de qualidade de fragmentos

Exemplo rápido:

# Dividir fragmentos por clusters
gtars fragsplit cluster-split --input fragments.tsv --clusters clusters.txt --output-dir ./by_cluster/

Veja references/cli.md para comandos de processamento de fragmentos.

6. Pontuação de Fragmentos

Pontue sobreposições de fragmentos contra datasets de referência.

Quando usar:

• Avaliar enriquecimento de fragmentos
• Comparar dados experimentais com referências
• Computação de métricas de qualidade
• Pontuação em lote entre amostras

Exemplo rápido:

# Pontuar fragmentos contra referência
gtars scoring score --fragments fragments.bed --reference reference.bed --output scores.txt

Workflows Comuns

Workflow 1: Análise de Sobreposição de Picos

Identifique características genômicas sobrepostas:

import gtars

# Carregar dois conjuntos de regiões
peaks = gtars.RegionSet.from_bed("chip_peaks.bed")
promoters = gtars.RegionSet.from_bed("promoters.bed")

# Encontrar sobreposições
overlapping_peaks = peaks.filter_overlapping(promoters)

# Exportar resultados
overlapping_peaks.to_bed("peaks_in_promoters.bed")

Workflow 2: Pipeline de Track de Cobertura

Gere tracks de cobertura para visualização:

# Etapa 1: Gerar cobertura
gtars uniwig generate --input atac_fragments.bed --output coverage.wig --resolution 10

# Etapa 2: Converter para BigWig para genome browsers
gtars uniwig generate --input atac_fragments.bed --output coverage.bw --format bigwig

Workflow 3: Pré-processamento de ML

Prepare dados genômicos para aprendizado de máquina:

from gtars.tokenizers import TreeTokenizer
import gtars

# Etapa 1: Carregar regiões de treinamento
regions = gtars.RegionSet.from_bed("training_peaks.bed")

# Etapa 2: Criar tokenizer
tokenizer = TreeTokenizer.from_bed_file("training_peaks.bed")

# Etapa 3: Tokenizar regiões
tokens = [tokenizer.tokenize(r.chromosome, r.start, r.end) for r in regions]

# Etapa 4: Usar tokens no pipeline de ML
# (integrar com geniml ou modelos personalizados)

Uso de Python vs CLI

Use API Python quando:

• Integrar com pipelines de análise
• Precisar de controle programático
• Trabalhar com NumPy/Pandas
• Construir workflows personalizados

Use CLI quando:

• Análises rápidas e únicas
• Scripting em shell
• Processamento em lote de arquivos
• Prototipar workflows

Documentação de Referência

Documentação abrangente de módulos:

• references/python-api.md - Referência completa da API Python com operações RegionSet, integração NumPy e exportação de dados
• references/overlap.md - Indexação IGD, detecção de sobreposições e operações de conjunto
• references/coverage.md - Geração de track de cobertura com uniwig
• references/tokenizers.md - Tokenização genômica para aplicações de ML
• references/refget.md - Gerenciamento de sequência de referência e digests
• references/cli.md - Referência completa da interface de linha de comando

Integração com geniml

Gtars funciona como a base para o pacote Python geniml, fornecendo operações principais de intervalo genômico para workflows de aprendizado de máquina. Ao trabalhar em tarefas relacionadas a geniml, use gtars para pré-processamento de dados e tokenização.

Características de Performance

• Performance nativa Rust: Execução rápida com baixa sobrecarga de memória
• Processamento paralelo: Operações multi-thread para grandes datasets
• Eficiência de memória: Suporte a streaming e memory-mapped files
• Operações zero-copy: Integração NumPy com cópia mínima de dados

Formatos de Dados

Gtars funciona com formatos genômicos padrão:

• BED: Intervalos genômicos (3 colunas ou estendido)
• WIG/BigWig: Tracks de cobertura
• FASTA: Sequências de referência
• Fragment TSV: Arquivos de fragmentos de célula única com códigos de barras

Tratamento de Erros e Depuração

Ative logging verboso para solução de problemas:

import gtars

# Ativar logging de debug
gtars.set_log_level("DEBUG")

# Modo verbose da CLI
gtars --verbose <command>