vep-rs
Documentation: https://natera-open-source.github.io/vep-rs/
A fast, memory-efficient reimplementation of the Ensembl Variant Effect Predictor (VEP) in Rust. It takes VEP's inputs and flags, writes VEP's consequence vocabulary in VEP's output formats, and annotates population-scale callsets two orders of magnitude faster than the Perl implementation.
In this README, "Ensembl VEP" is the reference implementation, ensemblorg/ensembl-vep, written in Perl; unqualified, it means release 116.2. The accompanying paper calls the same engine "VEP".
Why vep-rs instead of Ensembl VEP or fastVEP
| vep-rs v0.5.0 |
|---|
| Speed vs Ensembl VEP 116.2 | 396x faster on ARM (Graviton5), 254x on x86; 162x to 411x per dataset |
| Speed vs fastVEP v0.4.0 | 19.6x faster on ARM, 11.8x on x86; 9.2x to 22.4x per dataset |
| All of gnomAD v4.1 | 759,336,320 variants, 24 chromosomes: 624 s on one ARM machine, 1,012 s on x86 |
| Peak memory | At most 4.0 GB RSS on any chromosome |
| Concordance with Ensembl VEP | Adjusted F1 1.000000000 on all six whole-genome datasets, raw F1 0.999998408 pooled |
| Plugins | 10 built-in databases, plus C-ABI dynamic-library plugins |
| Output formats | VEP default, VCF, JSON, Tab, Parquet |
| Threading | --fork N; the default uses every logical CPU up to 32 |
The speed figures cover all of four population datasets (1,179,639,224 variants) under one protocol: the sum of per-chromosome medians at 16 threads, over 5 machines for vep-rs and fastVEP and over Ensembl VEP's one reference run per chromosome. The concordance figures cover those four plus the two genome-wide ClinVar releases, six whole-genome datasets in all (1,188,425,523 variants, 11,838,755,797 annotation tuples, 11,838,744,378 matched), against Ensembl VEP 116.2. The Current release section has the tables and the method.
The adjusted F1 sets aside only the documented cases where Ensembl VEP's own output is wrong, or where the two engines represent a record differently. Each case is traced to the mechanism in Ensembl VEP's source and reproducible from the record (docs/intended-divergences.md). Outside those cases every tuple matches, so vep-rs's remaining disagreements with Ensembl VEP are deliberate, documented corrections rather than defects.
The ten built-in plugin databases are CADD, REVEL, gnomADc, AlphaMissense, dbscSNV, LoFTEE, LoFtool and pLI on both GRCh37 and GRCh38, plus GWAS and SpliceAI on GRCh38. Dynamic-library plugins load from --dir_plugins (docs/plugins.md). Parquet output needs the duckdb CLI on PATH.
What "drop-in" means
vep-rs takes the same input files and flag names as Ensembl VEP and writes the same output layouts. Two things differ:
- The transcript cache. The cache is a directory built by
vep-cache-builder or converted from an Ensembl VEP cache (docs/cache-setup.md), found under --dir_cache, --species and --cache_version in Ensembl VEP's <dir_cache>/<species>/<version>_<assembly> layout or named directly with --json_cache; a run with no cache stops with an error, and vep-rs never contacts a database.
- Some flags are accepted but not implemented. Among them are
--custom and the statistics flags (vep-rs writes no summary file). --regulatory annotates regulatory and motif features from a converted Ensembl VEP cache (docs/regulatory.md). --refseq and --merged select the _refseq or _merged species directory, and --refseq also resolves an HGVS gene name among RefSeq transcripts first. The CLI reference and limitations page detail supported flags and omissions.
Installation
Pre-built binaries for Linux x86_64, Linux aarch64 and macOS aarch64 are on the Releases page; each Linux architecture has a measured archive and a generic one, and both run on glibc 2.17 or later. Building from source needs Rust 1.89+ (rustup):
git clone https://github.com/natera-open-source/vep-rs.git
cd vep-rs
cargo build --release
# Binary at target/release/vep
Each release from 0.2.0 on is also a container image, ghcr.io/natera-open-source/vep-rs, multi-platform from 0.5.0: the X.Y.Z, X.Y and latest tags carry the generic Linux binaries for linux/amd64 and linux/arm64 and run on Apple silicon and Graviton2 without a platform flag; X.Y.Z-x86-64-v3 and X.Y.Z-neoverse-v1 carry the measured binaries. The Installation page covers each archive's CPU floor, how much slower the generic archives are (each release page reports it, or that the release did not time them), how to build for an older CPU, and the image's tags, platforms and attestation.
Quick start
1. Try the bundled corpus
This needs no download. It runs the bundled 1,008-record excerpt of the benchmark datasets against the pruned GRCh37 cache that ships in tests/golden/:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
