API reference

vepyr.build_cache(release, cache_dir, *, cache_type, species='homo_sapiens', assembly='GRCh38', partitions=8, cache_format='parquet', local_cache=None, download_retries=10, show_progress=True, on_progress=None, overwrite=False)

Download an Ensembl VEP cache and convert it to an optimized cache.

Parameters:

Name	Type	Description	Default
release	int	Ensembl release number (e.g. 115).	required
cache_dir	str	Root directory for cache data and Parquet output.	required
cache_type	str	Required Ensembl VEP cache type: "ensembl", "merged", or "refseq".	required
species	str	Species name (default: "homo_sapiens").	'homo_sapiens'
assembly	str	Genome assembly (default: "GRCh38").	'GRCh38'
partitions	int	Number of DataFusion partitions for parallelism (default: 8).	8
cache_format	str	Cache format to build. Only "parquet" is supported (default).	'parquet'
local_cache	str or None	Path to an already-unpacked Ensembl VEP cache directory (the one containing info.txt). When provided, downloading and extraction are skipped entirely.	None
download_retries	int	Maximum number of resume-retries for the cache download (default: 10). Each retry resumes from the last byte received.	10
show_progress	bool	Show tqdm progress bars during conversion (default: True). .. note:: The partitioned-Parquet build path does not currently emit per-batch progress events, so no bars appear during the cache build regardless of show_progress / on_progress.	True
on_progress	callable or None	Custom progress callback with signature (entity, format, batch_rows, total_rows, total_expected). Overrides the default tqdm bars when provided. See the note on show_progress — the Parquet build path does not invoke it.	None
overwrite	bool	Rebuild existing cache outputs instead of skipping them.	False

Returns:

Type	Description
list[tuple[str, int]]	List of (parquet_file_path, row_count) for each written file.

vepyr.build_cache_entity(release, cache_dir, entity, *, cache_type, species='homo_sapiens', assembly='GRCh38', partitions=8, local_cache=None, download_retries=10, overwrite=False, chroms=None)

Download or open an Ensembl VEP cache and convert one raw entity.

This is the targeted counterpart to :func:build_cache. It applies the same exact release/source validation and writes into the same <release>_<assembly>_<cache_type> output directory. entity must be one of variation, transcript, exon, translation, regulatory, or motif. The raw translation entity produces the translation_core and translation_sift Parquet datasets.

chroms restricts the rebuild to specific contigs (e.g. ["chrX"]); None rebuilds every contig.

Returns a flattened list of (parquet_file_path, row_count) pairs.

vepyr.build_plugin_cache(plugin, version, *, source_path, cache_dir, plugin_cache_root, chroms=None, plugins_repo=None, overwrite=False)

Build a per-chromosome plugin cache.

plugin/version select plugins/<plugin>/<plugin>.source.toml from the public vepyr-plugins repo at that git tag (or plugins_repo for offline). Tiering is inherited from the variation cache at cache_dir. Returns per-chrom (chrom, rows, warm, cold) tuples.

source_path points each [[source]] at a real file, since the paths a manifest ships are placeholders. A single-source manifest takes a plain path; a manifest that declares several sources (each with a part) takes a {part: path} mapping, and every part must be mapped::

build_plugin_cache(
    "cadd", "v1.0",
    source_path={"snv": ".../whole_genome_SNVs.tsv.gz",
                 "indel": ".../gnomad.genomes.r4.0.indel.tsv.gz"},
    ...
)

The sources are registered as plugin_<name>_src_<part> and combined by the manifest's own ingest_sql -- there is no need to concatenate them first.

vepyr.annotate(vcf, cache_dir, *, everything=False, hgvs=False, hgvsc=False, hgvsp=False, shift_hgvs=None, no_escape=False, remove_hgvsp_version=False, hgvsp_use_prediction=False, reference_fasta=None, check_existing=False, af=False, af_1kg=False, af_gnomade=False, af_gnomadg=False, max_af=False, pubmed=False, cache_format='parquet', expected_cache_version=None, extended_probes=True, distance=None, gencode_basic=False, gencode_primary=False, all_refseq=False, exclude_predicted=False, pick=False, pick_allele=False, per_gene=False, pick_allele_gene=False, flag_pick=False, flag_pick_allele=False, flag_pick_allele_gene=False, pick_order=None, buffer_size=5000, failed=0, cache_size_mb=1024, workers=1, skip_csq=True, plugin_cache_root=None, plugins=None, output_vcf=None, preserve_record_layout=True, show_progress=True, compression=None, on_batch_written=None)

Annotate variants from a VCF file with VEP consequences.

Reads the VCF, runs annotate_vep() against the partitioned parquet cache produced by :func:build_cache, and returns a polars LazyFrame.

The engine auto-discovers context tables (transcript, exon, translation, regulatory, motif) from cache_dir subdirectories.

Parameters:

Name	Type	Description	Default
vcf	str	Path to the input VCF file.	required
cache_dir	str	Path to the parquet cache directory produced by :func:build_cache, e.g. "/data/vep/wgs/parquet/115_GRCh38_ensembl".	required
everything	bool	Enable all annotation features (80-field CSQ). Implies hgvs, af, check_existing, pubmed, etc. Requires reference_fasta.	False
hgvs	bool	Add HGVS notation. Implies hgvsc, hgvsp, shift_hgvs. Requires reference_fasta.	False
hgvsc	bool	Enable HGVSc notation (implied by hgvs/everything).	False
hgvsp	bool	Enable HGVSp notation (implied by hgvs/everything).	False
shift_hgvs	bool or None	3' shift HGVS notation. None = auto (True when hgvs enabled).	None
no_escape	bool	Don't URI-escape HGVS strings.	False
remove_hgvsp_version	bool	Remove version from HGVSp transcript ID.	False
hgvsp_use_prediction	bool	Use predicted rather than observed protein sequence.	False
reference_fasta	str or None	Path to reference FASTA (required for HGVS/everything).	None
check_existing	bool	Check for co-located known variants (implied by AF flags).	False
af	bool	Include allele frequencies.	False
af_1kg	bool	Include 1000 Genomes allele frequencies.	False
af_gnomade	bool	Include gnomAD exome allele frequencies.	False
af_gnomadg	bool	Include gnomAD genome allele frequencies.	False
max_af	bool	Include maximum AF across populations.	False
pubmed	bool	Include PubMed IDs for co-located variants.	False
extended_probes	bool	Use interval-overlap fallback for shifted indels (default: True).	True
distance	int or tuple[int, int] or None	Upstream/downstream distance for transcript overlap. Single int = both directions; tuple = (upstream, downstream).	None
gencode_basic	bool	Restrict to transcripts in the GENCODE basic set. Mutually exclusive with gencode_primary.	False
gencode_primary	bool	Restrict to transcripts in the GENCODE primary set (GRCh38 only). Mutually exclusive with gencode_basic.	False
all_refseq	bool	Keep all RefSeq transcripts including CCDS/EST-style rows.	False
exclude_predicted	bool	Exclude predicted RefSeq transcripts (XM_ / XR_ prefixes).	False
pick	bool	Emit one selected consequence per variant, matching VEP --pick.	False
pick_allele	bool	Emit one selected consequence per allele, matching VEP --pick_allele.	False
per_gene	bool	Emit one selected consequence per gene while retaining non-transcript rows, matching VEP --per_gene.	False
pick_allele_gene	bool	Emit one selected consequence per allele and gene, matching VEP --pick_allele_gene.	False
flag_pick	bool	Retain all consequences and add PICK=1 to one selected entry per variant, matching VEP --flag_pick.	False
flag_pick_allele	bool	Retain all consequences and add PICK=1 to one selected entry per allele, matching VEP --flag_pick_allele.	False
flag_pick_allele_gene	bool	Add a standalone PICK=1 CSQ field for the selected transcript per allele and gene, matching VEP --flag_pick_allele_gene.	False
pick_order	str or None	Comma-separated VEP pick ranking order, e.g. "biotype,rank,mane_select,tsl,canonical,appris,ccds,length".	None
buffer_size	int	Number of input variants per VEP-style annotation buffer. Defaults to Ensembl VEP's --buffer_size default of 5000.	5000
failed	int	Maximum allowed failed flag value from cache (default: 0).	0
cache_format	str	Cache format to use. Only "parquet" is supported (default).	'parquet'
expected_cache_version	str or None	Optional assertion against the cache version embedded in each requested chromosome's Parquet metadata. It cannot supply missing cache identity.	None
cache_size_mb	int	Annotation cache size in MB (default: 1024).	1024
workers	int	Number of within-contig fused annotation pipelines (default: 1). The single annotation-concurrency knob. 1 is serial; values greater than 1 require a tabix-indexed (bgzip + .tbi) input VCF.	1
skip_csq	bool	Exclude the raw CSQ column from the output (default: True). When True, only the parsed annotation columns are returned.	True
plugin_cache_root	str or None	Root of a plugin cache tree built by :func:build_plugin_cache, e.g. "/data/plugin_cache" holding plugin/<name>/ directories. Every plugin found under the root is applied — see plugins to narrow that — and its CSQ fields are added to the header and to each transcript. A plugin's version is fixed when its cache is built, not chosen here. None (default) applies no plugins and is byte-identical to a plugin-free run. Plugin values are appended to the CSQ field. With output_vcf the header names them; in a LazyFrame they are only inside the CSQ string, which the default skip_csq=True drops.	None
plugins	list of str or None	Restrict annotation to these plugin names, a subset of the directories under <plugin_cache_root>/plugin/. None (default) applies every plugin found there. An empty list applies none. Requires plugin_cache_root; an unknown name is an error rather than a silent skip. Selection works by handing the engine a root containing only the named plugins, hard-linked to the originals, so it costs no disk and no copy.	None
output_vcf	str or None	Path to write annotated VCF output. When set, annotation results are written directly to a VCF file and the output path is returned. When None (default), returns a polars LazyFrame. Compression is auto-detected from the file extension: .vcf for plain text, .vcf.gz or .vcf.bgz for block-gzipped (bgzf). Override with the compression parameter.	None
preserve_record_layout	bool	Write each record's INFO fields in the order the input wrote them, and its own FORMAT keys (default: True). Both are per record and neither survives the typed columns, so turning this off reorders INFO to schema order and drops any FORMAT key whose value is missing in every sample. Ensembl VEP keeps both by copying the input line and only appending to INFO, so byte agreement with it needs this on. Only used when output_vcf is set.	True
show_progress	bool	Show a progress bar on stderr during VCF output (default: True). Only used when output_vcf is set.	True
compression	str or None	VCF output compression. "bgzf" (block-gzip, tabix-compatible), "gzip", "plain", or None (auto-detect from extension). Only used when output_vcf is set.	None
on_batch_written	callable or None	Callback invoked after each batch is written to VCF, with signature (batch_rows: int, total_rows: int, total_input: int). total_rows is the cumulative number of VCF records written so far. total_input is the total number of input variants when known. Useful for driving tqdm progress bars in notebooks. Only used when output_vcf is set.	None

Returns:

Type	Description
LazyFrame or str	When output_vcf is None: annotated variants as a polars LazyFrame with typed annotation columns plus original VCF fields. When output_vcf is set: the output VCF file path.

Examples:

>>> import vepyr
>>> lf = vepyr.annotate("input.vcf", "/data/vep/parquet/115_GRCh38_ensembl")
>>> lf.collect()

>>> # Full annotation with all features
>>> lf = vepyr.annotate(
...     "input.vcf",
...     "/data/vep/parquet/115_GRCh38_ensembl",
...     everything=True,
...     reference_fasta="/ref/GRCh38.fa",
... )

>>> # Selective: HGVS + allele frequencies
>>> lf = vepyr.annotate(
...     "input.vcf",
...     "/data/vep/parquet/115_GRCh38_ensembl",
...     hgvs=True,
...     af=True,
...     af_gnomadg=True,
...     reference_fasta="/ref/GRCh38.fa",
... )

>>> # Write annotated VCF directly
>>> path = vepyr.annotate(
...     "input.vcf",
...     "/data/vep/parquet/115_GRCh38_ensembl",
...     everything=True,
...     reference_fasta="/ref/GRCh38.fa",
...     output_vcf="annotated.vcf",
... )