Quick start

1.

Download

git clone https://github.com/Ensembl/ensembl-vep.git

2. Install

cd ensembl-vep

perl INSTALL.pl

3.

What's new in release 112

Installation

Using VEP in Windows

Docker

Data formats

Documentation

Input

Output

Custom annotations

Data formats

gnomAD exomes and genomes

Citations and VEP users

- skipping API installation

cache files.

Downloading list of available cache files

specify multiple separated by spaces):

...

? 42

- downloading

https://ftp.ensembl.org/pub/release-112/variation/vep/homo_sapien

Enformer

Previous version history - from version 88: Show

Older versions (ensembl-tools) - until version 87: Show

VEP requires:

gcc, g++ and make

Perl version 5.10 or above recommended (tested on 5.10, 5.14, 5.18, 5.22, 5.26)

Perl packages:

Archive::Zip

DBD::mysql (version <=4.050)

DBI

VEP has been developed for UNIX-like environments and works well on Linux (e.g. Ubuntu,

Debian, Mint) and Mac OSX.

Run the following, and follow any prompts as they appear:

Additional non-essential components and enhancements must be installed manually.

BioPerl

ensembl

ensembl-io

will not affect any other Ensembl API installations.

The script will also attempt to install a Perl::XS module, Bio::DB::HTS , for rapid access to

bgzipped FASTA files. If this fails, you may add the --NO_HTSLIB flag when running the installer;

VEP will fall back to using Bio::DB::Fasta for this functionality (more details).

The installer is run on the command line as follows:

Follow on-screen prompts and note warnings of any files which will be deleted/overwritten

running the installer (for instance, export VEP_NO_HTSLIB=1 and export

VEP_DIR_PLUGINS="/plugins").

Please avoid using absolute paths to data as the paths inside the container differ from your local

machine.

1.

2.

Update your cache

INSTALL.pl -a c

Due to root requirements for the Docker daemon, using the Docker container for VEP is not

always possible to HPC users. Singularity, an alternative containerisation tool, does not assume

that you have a system where you are the root user. This has led to increased popularity in HPC

After installing Singularity , VEP may be used with Singularity based on the VEP Docker image

The Ensembl VEP API, plugins and their dependencies (e.g. Perl APIs, Bio::DB::HTS, htslib, ...)

are already installed in the image.

You can run the INSTALL.pl script to install the Cache data and FASTA files. For example, to set

up the cache and corresponding FASTA for human GRCh38 in your local folder

$HOME/vep_data:

Here is an example on running VEP with data from folder $HOME/vep_data in the local machine

Both the web and script version of VEP can use the same input formats. Formats can be auto-detected by the VEP script, but must be

manually selected when using the web interface.

VEP can use different input formats:

Format Variant example Structural variant example

Default VEP input 1 881907 881906 -/C + 1 160283 471362 DUP +

VCF 1 65568 . A C . . . 1 7936271 . N N[12:58877476[ . . SVTYPE=BND

HGVS identifiers ENST00000618231.3:c.9G>C ✗ Not supported

Variant identifiers rs699 nsv1000164

Genomic SPDI notation NC_000016.10:68684738:G:A ✗ Not supported

2.

start

3.

end

4.

allele - pair of alleles separated by a '/', with the reference allele first (or structural variant type)

5.

strand - defined as + (forward) or - (reverse). The strand will only be used for VEP to know which alleles to use.

6.

identifier - this identifier will be used in VEP's output. If not provided, VEP will construct an identifier from the given coordinates and

Structural variants are also supported by indicating a structural variant type instead of the allele:

VEP also supports using VCF (Variant Call Format) version 4.0 . This is a common format used by the 1000 genomes project, and can

be produced as an output format by many variant calling tools:

Structural variants are also supported depending on structural variant type.

of the VCF), then the identifier constructed and the position reported in VEP's output file will differ from the input.

1.

ensuring each variant has a unique identifier specified in the 3rd column of the VCF

2.

using VCF format as output (--vcf) - this preserves the formatting of your input coordinates and alleles

3.

using --minimal and --allele_number (see Complex VCF entries).

The following examples illustrate how VCF describes a variant and how it is handled internally by VEP. Consider the following aligned

sequences (for the purposes of discussion on chromosome 20):

Individual 1

The first individual shows a simple balanced substitution of G for C at base 3. This is described in a compatible manner in VCF and

Ensembl styles. Firstly, in VCF:

The upshot of this is that while in the VCF input file the position of the variant is reported as 2, in the output file from VEP the position will

be reported as 3. If no identifier is provided in the third column of the VCF, then the constructed identifier will be:

Individual 3

The third individual has an "A" inserted between the 3rd and 4th bases of the sequence relative to the reference. In VCF, as for the

deletion, the base before the insertion is included in both the reference and variant allele columns, and the reported position is that of the

preceding base:

For VCF entries with multiple alternate alleles, VEP will only trim the leading base from alleles if all REF and ALT alleles start with the

same base:

This will be considered internally by VEP as equivalent to:

Now consider the case where a single VCF line contains a representation of both a SNV and an insertion:

To modify this behaviour, VEP script users may use --minimal. This flag forces VEP to consider each REF/ALT pair independently,

trimming identical leading and trailing bases from each as appropriate. Since this can lead to confusing output regarding coordinates etc,

it is not the default behaviour. It is recommended to use the --allele_number flag to track the correspondence between alleles as input

and how they appear in the output.

Default VEP input

REST-style regions

VCF

TDUP - tandem duplication

Examples of structural variants encoded in VCF format:

See the VCF definition document for more detail on how to describe structural variants in VCF format.

See https://varnomen.hgvs.org for details. These must be relative to genomic or Ensembl transcript coordinates.

It also is possible to use RefSeq transcripts in both the web interface and the VEP script (see script documentation): this works for

RefSeq transcripts that align to the genome correctly.

Examples:

Examples using RefSeq identifiers (using --refseq in the VEP script, or select the otherfeatures transcript database on the web interface

change. The following example is for a permissable protein notation in dog (Canis familiaris):

variant identifiers (like nsv1000164 and esv1850194) are also supported.

VCF

Amino acid change - only given if the variant affects the protein-coding sequence

REF_ALLELE - the reference allele (after minimisation)

HIGH_INF_POS - a flag indicating if the variant falls in a high information position of a transcription factor binding profile (TFBP)

FREQS - Frequencies of overlapping variants used in filtering

ASN_AF - Frequency of existing variant in 1000 Genomes combined Asian population

gnomADe_AF - Frequency of existing variant in gnomAD exomes combined population

gnomADe_AFR_AF - Frequency of existing variant in gnomAD exomes African/American population

gnomADe_ASJ_AF - Frequency of existing variant in gnomAD exomes Ashkenazi Jewish population

gnomADe_EAS_AF - Frequency of existing variant in gnomAD exomes East Asian population

gnomADe_NFE_AF - Frequency of existing variant in gnomAD exomes Non-Finnish European population

gnomADe_OTH_AF - Frequency of existing variant in gnomAD exomes combined other combined populations

gnomADg_AFR_AF - Frequency of existing variant in gnomAD genomes African/American population

gnomADg_AMR_AF - Frequency of existing variant in gnomAD genomes American population

gnomADg_ASJ_AF - Frequency of existing variant in gnomAD genomes Ashkenazi Jewish population

gnomADg_EAS_AF - Frequency of existing variant in gnomAD genomes East Asian population

gnomADg_SAS_AF - Frequency of existing variant in gnomAD genomes South Asian population

CLIN_SIG - ClinVar clinical significance of the dbSNP variant

BIOTYPE - Biotype of transcript or regulatory feature

APPRIS - Annotates alternatively spliced transcripts as primary or alternate based on a range of computational methods. NB: not

available for GRCh37

TSL - Transcript support level. NB: not available for GRCh37

PUBMED - Pubmed ID(s) of publications that cite existing variant

SOMATIC - Somatic status of existing variant(s); multiple values correspond to multiple values in the Existing_variation field

PHENO - Indicates if existing variant is associated with a phenotype, disease or trait; multiple values correspond to multiple values

in the Existing_variation field

matches the underlying reference sequence and/or an Ensembl transcript (more information).

Options can be passed as the full string (e.g. --format), or as the shortest unique string among the options (e.g. --form for --format, since

there is another option --force_overwrite).

Flag Alternat

e

Description Incompatib

le with

copied to a config file that can be loaded in on the next run using --config. Not used

--gene_phenotype, --mirna

aliases on the server. Default = "homo_sapiens"

By default, VEP auto-detects the input file format. Using this option you can specify

by default

! Generate a HTML stats file (default). !

refseq or merged cache, (if installed).

! Specify the plugin directory to use. Default = "$HOME/.vep/" !

Specify a FASTA file or a directory containing FASTA files to use to

!

for VEP to pick up the alternate cache directory. This cache

contains transcript objects corresponding to RefSeq transcripts.

Consequence output will be given relative to these transcripts in

place of the default Ensembl transcripts (see documentation)

TCH,

BAM_EDIT

--

asic

--merged

! Use the merged Ensembl and RefSeq cache. Consequences are

flagged with the SOURCE of each transcript used.

REFSEQ_MA

TCH,

BAM_EDIT,

SOURCE

version). This should be used with Ensembl Genomes caches

! Sets the internal buffer size, corresponding to the number of

variants that are read in to memory simultaneously. Set this lower

to use less memory at the expense of longer run time, and higher

to use more memory with a faster run time. Default = 5000

!

Flag Alternate Description Output fields

! Use named plugin. Plugin modules should be installed in the Plugins

custom flag multiple times. See here for full details. Not used by default

! Use GFF transcript annotations in [filename] as an annotation source.

Requires a FASTA file of genomic sequence. Not used by default

! Use GTF transcript annotations in [filename] as an annotation source.

Requires a FASTA file of genomic sequence. Not used by default

! ADVANCED Use BAM file of sequence alignments to correct transcript

models not derived from reference genome sequence. Used to correct

derived from the overlapped transcript. This is especially relevant when

using the RefSeq cache, see documentation for more details. The

GIVEN_REF and USED_REF fields are set in the output to indicate any

change. Not used by default

! Using --bam or a BAM-edited RefSeq cache by default enables --

provided reference allele from the input. Not used by default

! By default, comma separated lists found within the INFO field of custom

annotation VCFs are assumed to be allele specific. For example, a

'single,double,triple' will associate triple with C, double with G and single

header. Output fields in the "CSQ" INFO field can be selected by

using --fields.

If the input format was VCF, the file will remain unchanged save for

the addition of the CSQ field (unless using any filtering).

Custom data added with --custom are added as separate fields,

using the key specified for each data file.

Commas in fields are replaced with ampersands (&) to preserve

Not used by default

--tab

--summary

--

most_sever

--vcf

For the tab format output, the selected fields may be those present

in the default output columns, or any of those that appear in the

For the VCF format output, the selected fields are those present

Example of command for the tab output:

Not used by default

consequence calculation i.e. sequence that is identical between

each pair of reference and alternate alleles is trimmed off from

both ends, with coordinates adjusted accordingly.

Note this may lead to discrepancies between input coordinates

and coordinates reported by VEP relative to transcript sequences;

variants have unique identifiers. The MINIMISED flag is set in the

VEP output where relevant. For an insertion/deletion, the allele is

e

le with

! Output the Sequence Ontology variant class. Not used by default VARIANT_

!

! Species limited SIFT predicts whether an amino acid substitution

--

most_sever

e

--summary

requires the Set::IntervalTree perl module.

! Modify the distance up and/or downstream between a variant and a

transcript for which VEP will assign the upstream_gene_variant or

modify both up- and downstream distances; prodiving two separated

by commas will set the up- (5') and down- (3') stream distances

! Report the proportion and length of a transcript overlapped by a

structural variant in VCF format.

! Indicates if the overlapped gene is associated with a phenotype,

!

! Report only regulatory regions that are found in the given cell type(s).

type in each cell type is reported under CELL_TYPE in the output. To

retrieve a list of cell types, use --cell_type list. Not used by default

!

! Consider only alternate alleles present in the genotypes of the

specified individual(s). May be a single individual, a comma-

--

individual_z

yg

! Consider alternate and reference alleles present in the genotypes of

the specified individual(s). May be a single individual, a comma-

list of individuals and their zygosity. Only works with VCF files

containing individual genotype data; individual IDs are taken from

column headers. Not used by default

--individual

! Force VCF genotypes to be interpreted as phased. For use with

plugins that depend on phased data. Not used by default

! Adds the uploaded allele string in the output (before minimisation). UPLOADE

!

! Adds affected exon and intron numbering to to output. Format is

! Don't overwrite existing CSQ entry in VCF INFO field. Overwrites by

! Change the name of the INFO key that VEP write the consequences

annotation centres to standardise descriptions of biological

sequences. Default = "SO"

--shift_hgvs

strand) before the HGVS notations are calculated; the flag

has shifted, relative to the input genomic coordinates. If

HGVS_OFFSET column. To disable the changing of location at

transcript level set --shift_hgvs to 0. Default: 1 (shift)

! Add version numbers to Ensembl transcript identifiers !

Not used by default

--

most_sever

e

! Adds the CCDS transcript identifer (where available) to the output.

! Adds best match accessions for translated protein products from

UniParc) to the output. Not used by default

Not used by default

e

! Adds a flag indicating if the transcript is the canonical transcript for

--

--

e

--summary

! Adds the biotype of the transcript or regulatory feature. Not used by

default

--

most_sever

--summary

! Adds names of overlapping protein domains to output. Not used by

default

most_sever

most_sever

! Load a file of chromosome synonyms. File should be tab-delimited

with the primary identifier in column 1 and the synonym in column 2.

Synonyms allow different chromosome identifiers to be used in the

input file and any annotation source (cache, database, GFF, custom

file, FASTA file). Not used by default

Flag Alternat

e

Description Output

Incompatib

le with

your input. By default the alleles are compared and variants on an

no_check_alleles.

! Return allele specific clinical significance. Setting this option to 0 will

provide all known clinical significance values at the given locus.

Default: 1 (Provide allele-specific annotations)

! Do not include variants with unknown alleles when checking for co-

located variants. Our human database contains variants from HGMD

default these are included when using --check_existing, use this flag

to exclude them. Not used by default

if your input variant has alleles A/G, and an existing co-located

Use this flag to disable this behaviour and compare using

coordinates alone. Not used by default

! Add the global allele frequency (AF) from 1000 Genomes Phase 3

data for any known co-located variant to the output. For this and all --

af_* flags, the frequency reported is for the input allele only, not

necessarily the non-reference or derived allele. Not used by default

! Report the highest allele frequency observed in any population from

! Include allele frequency from NHLBI-ESP populations. Must be

--database

Include allele frequency from Genome Aggregation Database

(gnomAD) exome populations. Note only data from the gnomAD

data set, see this guide. Must be used with --cache Not used by

! Include allele frequency from ExAC project populations. Must be

--database

The data content of VEP caches vary by species. This table shows the contents of the default human cache files in release 112.

Genome assembly GRCh38.p14 GRCh37.p13

MANE Version v1.3 n/a

GENCODE 46 19

RefSeq GCF_000001405.40-RS_2023_10

105.20220307

1000 Genomes Phase 3 (remapped) Phase 3

If you have Bio::DB::HTS (as set up by INSTALL.pl) or tabix installed on your system, the speed of retrieving existing co-located

A full description of the options can be seen using --help. When complete, VEP will automatically detect the converted cache and use