TileDB-VCF

Quando usar

Use para armazenamento de variantes de coorte, ingestão incremental de amostras, consultas de intervalo e exportação de subconjuntos para genômica downstream. O TileDB-VCF armazena registros; ele não realiza chamada conjunta de variantes, testes de associação, normalização ou ajuste de estrutura populacional. O tamanho do conjunto de dados por si só não determina se a execução na nuvem é apropriada: faça um benchmark da carga de trabalho pretendida de amostra, região e atributos.

Esta habilidade tem como alvo o TileDB-VCF 0.40.3 lançado. Verificações nativas de Python/CLI usaram dois VCFs sintéticos de amostra única no macOS ARM64. Os contratos do cliente 0.14.4 na nuvem foram verificados contra sua roda lançada e dispatch simulado; consultas e trabalhos hospedados não foram executados. Veja notas de instalação e verificação.

Instalar e verificar a pilha nativa

A distribuição Python tiledbvcf não é publicada no PyPI nesta revisão. O canal oficial tiledb Conda fornece tiledbvcf-py 0.40.3 para macOS ARM64, macOS x86-64 e Linux x86-64, com compilações Python 3.9-3.12. tiledb no PyPI é TileDB-Py e não instala TileDB-VCF. O Apple Silicon nativo não requer mais forçar CONDA_SUBDIR=osx-64.

Para o ambiente macOS ARM64 testado, os "pins" abaixo evitam falhas de importação de bibliotecas versionadas na resolução Conda atual, que de outra forma seria bem-sucedida:

conda create -n tiledb-vcf -c tiledb -c conda-forge \
  python=3.12 tiledbvcf-py=0.40.3 \
  azure-core-cpp=1.16.2 azure-storage-blobs-cpp=12.16.0 \
  azure-storage-files-datalake-cpp=12.14.0 capnproto=1.4.0 c-blosc2=2.23.1
conda activate tiledb-vcf
python -c 'import tiledbvcf; print(tiledbvcf.version)'
tiledbvcf version

A resolução/instalação Micromamba equivalente foi executada. Esses "pins" extras de ABI são uma solução alternativa verificada para macOS ARM64, não uma afirmação sobre todas as plataformas. Preserve o ambiente resolvido para produção. Instalação em outras plataformas e imagens Docker oficiais são alternativas documentadas upstream, não testadas aqui.

Preparar e criar uma coorte

1. Registre a montagem de referência, nomes/comprimentos de contigs, chamadores, regras de normalização, identidade da amostra e checksums de arquivos. Não misture montagens nem assuma que 1 e chr1 são equivalentes. Confirme cabeçalhos compatíveis entre as entradas.
2. Cada entrada deve conter uma amostra, ser ordenada por coordenadas e ter um índice. Use VCF ou BCF comprimido com BGZF e um correspondente .csi/.tbi. Inspecione bcftools query -l sample1.vcf.gz; nomes de arquivos não são identificadores de amostra.
3. Crie o conjunto de dados explicitamente e, em seguida, ingira. Abrir mode="w" sozinho não cria seu esquema. Materialize campos lidos com frequência no momento da criação.
4. Valide um pequeno intervalo conhecido e uma exportação de ida e volta antes de escalar.

Para VCFs de texto simples ordenados existentes (execute uma vez por entrada; nomes de saída devem ser novos):

bcftools view -Oz -o sample1.vcf.gz sample1.vcf
bcftools index -c sample1.vcf.gz
bcftools view -Oz -o sample2.vcf.gz sample2.vcf
bcftools index -c sample2.vcf.gz

Os seguintes exemplos locais foram exercitados com IDs de amostra S1 e S2, contig chr1 e coordenadas 1-100; substitua os IDs e intervalos verificados em dados reais.

import tiledbvcf

uri = "cohort"
config = {"sm.compute_concurrency_level": "2", "sm.io_concurrency_level": "2"}
with tiledbvcf.Dataset(uri, mode="w", tiledb_config=config) as ds:
    ds.create_dataset(extra_attrs=["fmt_GT", "fmt_DP"])
    ds.ingest_samples(
        ["sample1.vcf.gz"], threads=2, total_memory_budget_mb=512
    )

# Incremental ingestion uses the existing dataset; do not call create_dataset again.
with tiledbvcf.Dataset(uri, mode="w", tiledb_config=config) as ds:
    ds.ingest_samples(
        ["sample2.vcf.gz"], threads=2, total_memory_budget_mb=512
    )

O array de dados schema-v4 tem contig, coordenada inicial e dimensões de amostra; cabeçalhos e estatísticas opcionais são arrays separados no grupo de conjunto de dados. Campos não materializados explicitamente permanecem nos payloads INFO/FORMAT. Nomes de consulta como pos_start não precisam corresponder aos nomes de coluna de armazenamento brutos.

Upstream suporta ingestão paralela por threads/processos. Atribua trabalho de amostra distinto e operações de ciclo de vida/manutenção de coordenadas; não reingira amostras cegamente. resume=True suporta ingestão interrompida, não correção arbitrária de duplicatas.

Consultar completamente e interpretar coordenadas corretamente

…