/tiledbvcf

name: tiledbvcf
description: Efficient storage and retrieval of genomic variant data using TileDB. Scalable VCF/BCF ingestion, incremental sample addition, compressed storage, parallel queries, and export capabilities for population genomics.
license: MIT license
metadata:
  version: "1.1"
  skill-author: Jeremy Leipzig

TileDB-VCF

Overview

TileDB-VCF is a high-performance C++ library with Python and CLI interfaces for efficient storage and retrieval of genomic variant-call data. Built on TileDB's sparse array technology, it enables scalable ingestion of VCF/BCF files, incremental sample addition without expensive merging operations, and efficient parallel queries of variant data stored locally or in the cloud.

When to Use This Skill

This skill should be used when:

• Learning TileDB-VCF concepts and workflows
• Prototyping genomics analyses and pipelines
• Working with small-to-medium datasets (< 1000 samples)
• Need incremental addition of new samples to existing datasets
• Require efficient querying of specific genomic regions across many samples
• Working with cloud-stored variant data (S3, Azure, GCS)
• Need to export subsets of large VCF datasets
• Building variant databases for cohort studies
• Educational projects and method development
• Performance is critical for variant data operations

Quick Start

Installation

**Preferred Method: Conda/Mamba**

# Enter the following two lines if you are on a M1 Mac
CONDA_SUBDIR=osx-64
conda config --env --set subdir osx-64

# Create the conda environment
conda create -n tiledb-vcf "python<3.10"
conda activate tiledb-vcf

# Mamba is a faster and more reliable alternative to conda
conda install -c conda-forge mamba

# Install TileDB-Py and TileDB-VCF, align with other useful libraries
mamba install -y -c conda-forge -c bioconda -c tiledb tiledb-py tiledbvcf-py pandas pyarrow numpy

**Alternative: Docker Images**

docker pull tiledb/tiledbvcf-py     # Python interface
docker pull tiledb/tiledbvcf-cli    # Command-line interface

Basic Examples

**Create and populate a dataset:**

import tiledbvcf

# Create a new dataset
ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
                      cfg=tiledbvcf.ReadConfig(memory_budget=1024))

# Ingest VCF files (must be single-sample with indexes)
# Requirements:
# - VCFs must be single-sample (not multi-sample)
# - Must have indexes: .csi (bcftools) or .tbi (tabix)
ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])

**Query variant data:**

# Open existing dataset for reading
ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")

# Query specific regions and samples
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())

**Export to VCF:**

import os

# Export two VCF samples
ds.export(
    regions=["chr21:8220186-8405573"],
    samples=["HG00101", "HG00097"],
    output_format="v",
    output_dir=os.path.expanduser("~"),
)

Core Capabilities

1. Dataset Creation and Ingestion

Create TileDB-VCF datasets and incrementally ingest variant data from multiple VCF/BCF files. This is appropriate for building population genomics databases and cohort studies.

**Requirements:**

• **Single-sample VCFs only**: Multi-sample VCFs are not supported
• **Index files required**: VCF/BCF files must have indexes (.csi or .tbi)

**Common operations:**

• Create new datasets with optimized array schemas
• Ingest single or multiple VCF/BCF files in parallel
• Add new samples incrementally without re-processing existing data
• Configure memory usage and compression settings
• Handle various VCF formats and INFO/FORMAT fields
• Resume interrupted ingestion processes
• Validate data integrity during ingestion

2. Efficient Querying and Filtering

Query variant data with high performance across genomic regions, samples, and variant attributes. This is appropriate for association studies, variant discovery, and population analysis.

**Common operations:**

• Query specific genomic regions (single or multiple)
• Filter by sample names or sample groups
• Extract specific variant attributes (position, alleles, genotypes, quality)
• Access INFO and FORMAT fields efficiently
• Combine spatial and attribute-based filtering
• Stream large query results
• Perform aggregations across samples or regions

3. Data Export and Interoperability

Export data in various formats for downstream analysis or integration with other genomics tools. This is appropriate for sharing datasets, creating analysis subsets, or feeding other pipelines.

**Common operations:**

• Export to standard VCF/BCF formats
• Generate TSV files with selected fields
• Create sample/region-specific subsets
• Maintain data provenance and metadata
• Lossless data export preserving all annotations
• Compressed output formats
• Streaming exports for large datasets

4. Population Genomics Workflows

TileDB-VCF excels at large-scale population genomics analyses requiring efficient access to variant data across many samples and genomic regions.

**Common workflows:**

• Genome-wide association studies (GWAS) data preparation
• Rare variant burden testing
• Population stratification analysis
• Allele frequency calculations across populations
• Quality control across large cohorts
• Variant annotation and filtering
• Cross-population comparative analysis

Key Concepts

Array Schema and Data Model

**TileDB-VCF Data Model:**

• Variants stored as sparse arrays with genomic coordinates as dimensions
• Samples stored as attributes allowing efficient sample-specific queries
• INFO and FORMAT fields preserved with original data types
• Automatic compression and chunking for optimal storage

**Schema Configuration:**

# Custom schema with specific tile extents
config = tiledbvcf.ReadConfig(
    memory_