TileDB-VCF
Visão Geral
O TileDB-VCF é uma biblioteca C++ de alto desempenho com interfaces Python e CLI para armazenamento e recuperação eficientes de dados de chamadas de variantes genômicas. Construído sobre a tecnologia de arrays esparsos do TileDB, ele permite a ingestão escalável de arquivos VCF/BCF, adição incremental de amostras sem operações de mesclagem caras e consultas paralelas eficientes de dados de variantes armazenados localmente ou na nuvem.
Quando Usar Esta Habilidade
Esta habilidade deve ser usada quando:
- Aprendendo conceitos e fluxos de trabalho do TileDB-VCF
- Prototipando análises e pipelines genômicos
- Trabalhando com conjuntos de dados de pequeno a médio porte (< 1000 amostras)
- Precisando adicionar novas amostras incrementalmente a conjuntos de dados existentes
- Exigindo consultas eficientes de regiões genômicas específicas em muitas amostras
- Trabalhando com dados de variantes armazenados em nuvem (S3, Azure, GCS)
- Precisando exportar subconjuntos de grandes conjuntos de dados VCF
- Construindo bancos de dados de variantes para estudos de coorte
- Projetos educacionais e desenvolvimento de métodos
- O desempenho é crítico para operações com dados de variantes
Início Rápido
Instalação
Método Preferido: Conda/Mamba
# Insira as duas linhas a seguir se estiver em um Mac M1
CONDA_SUBDIR=osx-64
conda config --env --set subdir osx-64
# Crie o ambiente conda
conda create -n tiledb-vcf "python<3.10"
conda activate tiledb-vcf
# Mamba é uma alternativa mais rápida e confiável ao conda
conda install -c conda-forge mamba
# Instale TileDB-Py e TileDB-VCF, alinhados com outras bibliotecas úteis
mamba install -y -c conda-forge -c bioconda -c tiledb tiledb-py tiledbvcf-py pandas pyarrow numpy
Alternativa: Imagens Docker
docker pull tiledb/tiledbvcf-py # Interface Python
docker pull tiledb/tiledbvcf-cli # Interface de linha de comando
Exemplos Básicos
Criar e popular um conjunto de dados:
import tiledbvcf
# Crie um novo conjunto de dados
ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
cfg=tiledbvcf.ReadConfig(memory_budget=1024))
# Ingerir arquivos VCF (devem ser de amostra única com índices)
# Requisitos:
# - VCFs devem ser de amostra única (não multi-amostra)
# - Devem ter índices: .csi (bcftools) ou .tbi (tabix)
ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])
Consultar dados de variantes:
# Abrir conjunto de dados existente para leitura
ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")
# Consultar regiões e amostras específicas
df = ds.read(
attrs=["sample_name", "pos_start", "pos_end", "alleles", "fmt_GT"],
regions=["chr1:1000000-2000000", "chr2:500000-1500000"],
samples=["sample1", "sample2", "sample3"]
)
print(df.head())
Exportar para VCF:
import os
# Exportar duas amostras VCF
ds.export(
regions=["chr21:8220186-8405573"],
samples=["HG00101", "HG00097"],
output_format="v",
output_dir=os.path.expanduser("~"),
)
Capacidades Principais
1. Criação e Ingestão de Conjuntos de Dados
Crie conjuntos de dados TileDB-VCF e ingira incrementalmente dados de variantes de vários arquivos VCF/BCF. Isso é apropriado para construir bancos de dados de genômica populacional e estudos de coorte.
Requisitos:
- Apenas VCFs de amostra única: VCFs multi-amostra não são suportados
- Arquivos de índice necessários: Arquivos VCF/BCF devem ter índices (.csi ou .tbi)
Operações comuns:
- Criar novos conjuntos de dados com esquemas de array otimizados
- Ingerir arquivos VCF/BCF únicos ou múltiplos em paralelo
- Adicionar novas amostras incrementalmente sem reprocessar dados existentes
- Configurar uso de memória e configurações de compressão
- Lidar com vários formatos VCF e campos INFO/FORMAT
- Retomar processos de ingestão interrompidos
- Validar a integridade dos dados durante a ingestão
2. Consulta e Filtragem Eficientes
Consulte dados de variantes com alto desempenho em regiões genômicas, amostras e atributos de variantes. Isso é apropriado para estudos de associação, descoberta de variantes e análise populacional.
Operações comuns:
- Consultar regiões genômicas específicas (únicas ou múltiplas)
- Filtrar por nomes de amostras ou grupos de amostras
- Extrair atributos específicos de variantes (posição, alelos, genótipos, qualidade)
- Acessar campos INFO e FORMAT de forma eficiente
- Combinar filtragem espacial e baseada em atributos
- Transmitir grandes resultados de consulta
- Realizar agregações entre amostras ou regiões
3. Exportação e Interoperabilidade de Dados
Exporte dados em vários formatos para análise downstream ou integração com outras ferramentas genômicas. Isso é apropriado para compartilhar conjuntos de dados, criar subconjuntos de análise ou alimentar outros pipelines.
Operações comuns:
- Exportar para formatos padrão VCF/BCF
- Gerar arquivos TSV com campos selecionados
- Criar subconjuntos específicos de amostras/regiões
- Manter proveniência e metadados dos dados
- Exportação sem perdas preservando todas as anotações
- Formatos de saída compactados
- Exportações em streaming para grandes conjuntos de dados
4. Fluxos de Trabalho em Genômica Populacional
O TileDB-VCF se destaca em análises de genômica populacional em larga escala que exigem acesso eficiente a dados de variantes em muitas amostras e regiões genômicas.
Fluxos de trabalho comuns:
- Preparação de dados para estudos de associação genômica ampla (GWAS)
- Testes de carga de variantes raras
- Análise de estratificação populacional
- Cálculos de frequência alélica entre populações
- Controle de qualidade em grandes coortes
- Anotação e filtragem de variantes
- Análise comparativa entre populações
Conceitos Chave
Esquema do Array e Modelo de Dados
Modelo de Dados do TileDB-VCF:
- Variantes armazenadas como arrays esparsos com coordenadas genômicas como dimensões
- Amostras armazenadas como atributos, permitindo consultas eficientes específicas por amostra
- Campos INFO e FORMAT preservados com tipos de dados originais
- Compressão e fragmentação automáticas para armazenamento otimizado
Configuração do Esquema:
# Esquema personalizado com extensões de tile específicas
config = tiledbvcf.ReadConfig(
memory_budget=2048, # MB
region_partition=(0, 3095677412), # Genoma completo
sample_partition=(0, 10000) # Até 10k amostras
)
Sistemas de Coordenadas e Regiões
Crítico: O TileDB-VCF usa coordenadas genômicas baseadas em 1 seguindo o padrão VCF:
- As posições são baseadas em 1 (a primeira base é a posição 1)
- Os intervalos são inclusivos em ambas as extremidades
- A região "chr1:1000-2000" inclui as posições 1000-2000 (1001 bases no total)
Formatos de especificação de região:
# Região única
regions = ["chr1:1000000-2000000"]
# Múltiplas regiões
regions = ["chr1:1000000-2000000", "chr2:500000-1500000"]
# Cromossomo inteiro
regions = ["chr1"]
# Estilo BED (baseado em 0, semi-aberto convertido internamente)
regions = ["chr1:999999-2000000"] # Equivalente a chr1:1000000-2000000 baseado em 1
Gerenciamento de Memória
Considerações de desempenho:
- Defina um orçamento de memória apropriado com base na memória do sistema disponível
- Use consultas em streaming para conjuntos de resultados muito grandes
- Particione grandes ingestões para evitar esgotamento de memória
- Configure o cache de tiles para acesso repetido a regiões
- Use ingestão paralela para vários arquivos
- Otimize consultas de região combinando regiões próximas
Integração com Armazenamento em Nuvem
O TileDB-VCF funciona perfeitamente com armazenamento em nuvem:
# Conjunto de dados S3
ds = tiledbvcf.Dataset(uri="s3://bucket/dataset", mode="r")
# Azure Blob Storage
ds = tiledbvcf.Dataset(uri="azure://container/dataset", mode="r")
# Google Cloud Storage
ds = tiledbvcf.Dataset(uri="gcs://bucket/dataset", mode="r")
Armadilhas Comuns
- Esgotamento de memória durante a ingestão: Use orçamento de memória apropriado e processamento em lote para arquivos VCF grandes
- Consultas de região ineficientes: Combine regiões próximas em vez de muitas consultas separadas
- Nomes de amostras ausentes: Certifique-se de que os nomes das amostras nos cabeçalhos VCF correspondam às especificações de consulta
- Confusão no sistema de coordenadas: Lembre-se de que o TileDB-VCF usa coordenadas baseadas em 1 como o padrão VCF
- Conjuntos de resultados grandes: Use streaming ou paginação para consultas que retornam milhões de variantes
- Permissões de nuvem: Garanta a autenticação adequada para acesso ao armazenamento em nuvem
- Acesso concorrente: Vários escritores no mesmo conjunto de dados podem causar corrupção—use bloqueio apropriado
Uso da CLI
O TileDB-VCF fornece uma interface de linha de comando com os seguintes subcomandos:
Subcomandos Disponíveis:
create- Cria um conjunto de dados TileDB-VCF vaziostore- Ingere amostras em um conjunto de dados TileDB-VCFexport- Exporta dados de um conjunto de dados TileDB-VCFlist- Lista todos os nomes de amostras presentes em um conjunto de dados TileDB-VCFstat- Imprime estatísticas de alto nível sobre um conjunto de dados TileDB-VCFutils- Utilitários para trabalhar com um conjunto de dados TileDB-VCFversion- Imprime as informações da versão e sai
# Criar conjunto de dados vazio
tiledbvcf create --uri my_dataset
# Ingerir amostras (requer VCFs de amostra única com índices)
tiledbvcf store --uri my_dataset --samples sample1.vcf.gz,sample2.vcf.gz
# Exportar dados
tiledbvcf export --uri my_dataset \
--regions "chr1:1000000-2000000" \
--sample-names "sample1,sample2"
# Listar todas as amostras
tiledbvcf list --uri my_dataset
# Mostrar estatísticas do conjunto de dados
tiledbvcf stat --uri my_dataset
Recursos Avançados
Análise de Frequência Alélica
# Calcular frequências alélicas
af_df = tiledbvcf.read_allele_frequency(
uri="my_dataset",
regions=["chr1:1000000-2000000"],
samples=["sample1", "sample2", "sample3"]
)
Controle de Qualidade de Amostras
# Realizar QC de amostras
qc_results = tiledbvcf.sample_qc(
uri="my_dataset",
samples=["sample1", "sample2"]
)
Configurações Personalizadas
# Configuração avançada
config = tiledbvcf.ReadConfig(
memory_budget=4096,
tiledb_config={
"sm.tile_cache_size": "1000000000",
"vfs.s3.region": "us-east-1"
}
)
Recursos
Obtendo Ajuda
Recursos Open Source do TileDB-VCF
Documentação Open Source:
- TileDB Academy: https://cloud.tiledb.com/academy/
- Guia de Genômica Populacional: https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/
- TileDB-VCF GitHub: https://github.com/TileDB-Inc/TileDB-VCF
Recursos do TileDB-Cloud
Para Genômica em Larga Escala/Produção:
- Plataforma TileDB-Cloud: https://cloud.tiledb.com
- TileDB Academy (Toda a Documentação): https://cloud.tiledb.com/academy/
Primeiros Passos:
- Cadastro de conta gratuita: https://cloud.tiledb.com
- Contato: [email protected] para necessidades empresariais
Escalando para o TileDB-Cloud
Quando suas cargas de trabalho genômicas superam o processamento em nó único, o TileDB-Cloud fornece capacidades de nível empresarial para pipelines de genômica de produção.
Nota: Esta seção cobre as capacidades do TileDB-Cloud com base na documentação disponível. Para detalhes completos da API e funcionalidades atuais, consulte a documentação oficial do TileDB-Cloud e a referência da API.
Configurando o TileDB-Cloud
1. Criar Conta e Obter Token de API
# Cadastre-se em https://cloud.tiledb.com
# Gere o token de API nas configurações da sua conta
2. Instalar o Cliente Python do TileDB-Cloud
# Instalação base
uv pip install tiledb-cloud
# Com funcionalidade específica para genômica
uv pip install tiledb-cloud[life-sciences]
3. Configurar Autenticação
# Defina a variável de ambiente com seu token de API
export TILEDB_REST_TOKEN="your_api_token"
import tiledb.cloud
# A autenticação é automática via TILEDB_REST_TOKEN
# Nenhum login explícito necessário no código
Migrando do Open Source para o TileDB-Cloud
Ingestão em Larga Escala
# TileDB-Cloud: Ingestão distribuída de VCF
import tiledb.cloud.vcf
# Use o módulo de ingestão de VCF especializado
# Nota: A API exata requer documentação do TileDB-Cloud
# Isso representa a estrutura de funcionalidades disponíveis
tiledb.cloud.vcf.ingestion.ingest_vcf_dataset(
source="s3://my-bucket/vcf-files/",
output="tiledb://my-namespace/large-dataset",
namespace="my-namespace",
acn="my-s3-credentials",
ingest_resources={"cpu": "16", "memory": "64Gi"}
)
Processamento Distribuído de Consultas
# TileDB-Cloud: Consulta de VCF em armazenamento distribuído
import tiledb.cloud.vcf
import tiledbvcf
# Defina o URI do conjunto de dados
dataset_uri = "tiledb://TileDB-Inc/gvcf-1kg-dragen-v376"
# Obtenha todas as amostras do conjunto de dados
ds = tiledbvcf.Dataset(dataset_uri, tiledb_config=cfg)
samples = ds.samples()
# Defina atributos e intervalos para consultar
attrs = ["sample_name", "fmt_GT", "fmt_AD", "fmt_DP"]
regions = ["chr13:32396898-32397044", "chr13:32398162-32400268"]
# Realize a leitura, que é executada de forma distribuída
df = tiledb.cloud.vcf.read(
dataset_uri=dataset_uri,
regions=regions,
samples=samples,
attrs=attrs,
namespace="my-namespace", # especifica qual conta será cobrada
)
df.to_pandas()
Recursos Empresariais
Compartilhamento e Colaboração de Dados
# O TileDB-Cloud fornece capacidades empresariais de compartilhamento de dados
# através de permissões baseadas em namespace e gerenciamento de grupos
# Acesse conjuntos de dados compartilhados via URIs do TileDB-Cloud
dataset_uri = "tiledb://shared-namespace/population-study"
# Colabore através de notebooks e recursos computacionais compartilhados
# (A API específica requer documentação do TileDB-Cloud)
Otimização de Custos
- Computação Serverless: Pague apenas pelo tempo de computação real
- Auto-scaling: Escale automaticamente para cima/baixo com base na carga de trabalho
- Instâncias Spot: Use computação otimizada de custos para trabalhos em lote
- Tiering de Dados: Gerenciamento automático de armazenamento hot/cold
Segurança e Conformidade
- Criptografia de Ponta a Ponta: Dados criptografados em trânsito e em repouso
- Controles de Acesso: Permissões granulares e logs de auditoria
- Conformidade HIPAA/SOC2: Padrões de segurança empresarial
- Suporte a VPC: Implante em ambientes de nuvem privada
Lista de Verificação para Migração
✅ Migre para o TileDB-Cloud se você tiver:
- Conjuntos de dados > 1000 amostras
- Necessidade de processar > 100GB de dados VCF
- Exigir computação distribuída
- Múltiplos membros da equipe precisando de acesso
- Necessidade de segurança/conformidade empresarial
- Desejo de computação serverless otimizada de custos
- Exigir disponibilidade de produção 24/7
Primeiros Passos com o TileDB-Cloud
- Comece Gratuito: O TileDB-Cloud oferece nível gratuito para avaliação
- Suporte à Migração: A equipe TileDB fornece assistência à migração
- Treinamento: Acesso a tutoriais específicos de genômica