vcfcache 0.5.0

Cache-based VCF annotation accelerator

VCFcache – Cache once, annotate fast

Cache common variants once, reuse them for every sample. VCFcache builds a normalized blueprint, annotates it once, and reuses those results so only rare/novel variants are annotated at runtime.

Performance: With 60-90% cache hit rates on typical samples, VCFcache achieves 2-10× speed-ups compared to standard annotation pipelines. Cache lookups are constant-time operations regardless of cache size, making the tool highly scalable. See WIKI.md for the detailed runtime efficiency model.

Contig naming: VCFcache requires matching contig naming between cache and samples (e.g., both use chr1 or both use 1). At runtime, vcfcache reports the contig overlap and fails fast if there is no overlap.

Works with any genome/build (human, mouse, plants, model organisms) as long as your inputs and annotation pipeline use compatible reference builds and contig naming. The genome build must be explicitly set in both params.yaml and annotation.yaml.

---

Quick Start - pip install

Requires: Python >= 3.11 (earlier versions untested), bcftools >= 1.20

pip install vcfcache
vcfcache demo --smoke-test  # Run comprehensive demo
vcfcache --help

Install bcftools separately:

• Ubuntu/Debian: sudo apt-get install bcftools
• macOS: brew install bcftools
• Conda: conda install -c bioconda bcftools

---

Quick Start - Docker

Docker includes bcftools - no separate installation needed.

docker pull ghcr.io/julius-muller/vcfcache:latest

# List available public caches
docker run --rm ghcr.io/julius-muller/vcfcache:latest list caches

# Use a public cache from Zenodo
docker run --rm -v $(pwd):/work ghcr.io/julius-muller/vcfcache:latest \
  annotate \
    -a cache-hg38-gnomad-4.1joint-AF0100-vep-115.2-basic \
    --vcf /work/sample.vcf.gz \
    --output /work/sample_vc.bcf \
    --stats-dir /work

---

Quick Start - from source

git clone https://github.com/julius-muller/vcfcache.git
cd vcfcache
uv venv .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
vcfcache --help

---

Build Your Own Cache

1. Create blueprint (normalize/deduplicate variants):

vcfcache blueprint-init --vcf gnomad.bcf --output ./cache -y params.yaml

2. Annotate blueprint (create cache):

vcfcache cache-build --name vep_cache --db ./cache -a annotation.yaml -y params.yaml

3. Use cache on samples:

vcfcache annotate -a ./cache/cache/vep_cache --vcf sample.vcf.gz --output ./sample_vc.bcf --stats-dir ./results

If --stats-dir is provided, stats are written to <stats_dir>/<input_basename>_vcstats. Otherwise, they default to <cwd>/<input_basename>_vcstats. Use --no-stats to skip writing stats/logs (disables vcfcache compare).

---

Configuration

Override system bcftools (if needed):

export VCFCACHE_BCFTOOLS=/path/to/bcftools-1.22

Change where downloaded caches/blueprints are stored (default: ~/.cache/vcfcache):

export VCFCACHE_DIR=/path/to/vcfcache_cache_dir

Or in params.yaml:

bcftools_cmd: "/path/to/bcftools"

See WIKI.md for detailed configuration, cache distribution via Zenodo, and troubleshooting.

---

Links

• Documentation: WIKI.md
• Source: https://github.com/julius-muller/vcfcache
• Issues: https://github.com/julius-muller/vcfcache/issues
• Docker: ghcr.io/julius-muller/vcfcache