VEP is a powerful and flexible tool for annotating, analyzing, and prioritizing genomic variants. It is particularly useful in cancer genomics, where understanding the functional impact of somatic mutations is crucial for research and clinical applications. We can answer questions like:
How damaging is a certain somatic mutation (according to reference databases)
What is the impact of this mutation in the particular cancer type of study
Is the mutation known for that cancer?
Is there a relation with a certain mutation and a chemotherapeutic (or a class of them)
Why do we need a tool like VEP?
In the genomic era we can get thousands of somatic mutations and those are rarely analyzed one by one. We need a way to summarize those SNVs consistently and to understand which are the variants to focus on. In this context a tool like VEP becomes very useful.
Key Concepts
Install VEP
NoteVEP Version
This course uses VEP v115 (2025). Some features and default behaviors may differ in other versions. Always check the release notes for your version.
VEP is already pre-installed on the cloud server. In order to load the environment, run:
mamba activate ngs-tools
If you want to install VEP locally or on your compute cluster, you can follow the instructions below.
NoteInstructions for local install
# Installing Conda #https://docs.anaconda.com/miniconda/mkdir-p ~/miniconda3wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.shbash ~/miniconda3/miniconda.sh -b-u-p ~/miniconda3rm ~/miniconda3/miniconda.shsource ~/miniconda3/bin/activateconda init --all# Using Condaconda create -n vep samtools python=3.10 ensembl-vep=115# conda install -c bioconda ensembl-vep=115 # if installing in current env# Activate VEP's envconda activate vep# PLEASE DO RUN During the course, only if you follow locally# Install all the data locally#vep_install -a cf -s homo_sapiens -y GRCh38 --CONVERT (this command will download in $HOME/.vep the cache folder)#vep_install -a cf -s homo_sapiens -y GRCh38 -c $HOME/project/course_data/vep --CONVERT (this specify the cache folder)# Plugins installation# vep_install -a p --PLUGINS all
Instead of conda you could try installing mamba. If you are on Unix-based system this is simple mamba. If you are following along the course, mamba is already installed for you, with all the software required for this course. In this case you can activate the enviroment with mamba activate ngs-tools.
Transcript Selection
VEP can report consequences for all transcripts overlapping a variant. However, this often results in multiple annotations per variant. Several approaches are available to handle this:
--pick: Selects one consequence per variant based on a predefined hierarchy (e.g., HIGH > MODERATE > LOW > MODIFIER)
--pick_allele: Selects one consequence per variant allele
--pick_allele_gene: Selects one consequence per variant allele per gene
--per_gene: Selects one consequence per gene
--flag_pick: Flags the selected consequence while retaining others
Consequence Priority
VEP ranks consequences by severity: Figure 1: Image from the Ensembl VEP website.
Consequence
Impact
Description
Transcript ablation
HIGH
Complete deletion of a gene transcript
Splice acceptor variant
HIGH
Variant at the 3’ end of an intron that disrupts RNA splicing
Splice donor variant
HIGH
Variant at the 5’ end of an intron that disrupts RNA splicing
Variant removes stop codon, extending protein length
Start lost
HIGH
Loss of start codon prevents proper translation initiation
Transcript amplification
HIGH
Increased copy number of transcript regions
Inframe insertion
MODERATE
Insertion of bases in multiples of 3, no frameshift
Inframe deletion
MODERATE
Deletion of bases in multiples of 3, no frameshift
Missense variant
MODERATE
Single nucleotide change causing amino acid substitution
Protein altering variant
MODERATE
Variant changes protein sequence
Practical Exercises
In case that you do not have the Mutect2 call and/or the CNVkit call, you can obtain those from here. In this folder there are also a README.md and some folders containing preprocessed data for the additional resources that we will use with Ensembl-VEP. The script that is used to download all the databases resources mentioned in the exercises is in the course repo’s scripts folder.
If you are following along the course you should download and extract the data into your $HOME/project/ folder.
Caution--cache option
By default VEP will install the cache and plugins into your home folder (~/.vep/) and if that is the case, then you can leave it like --cache. - If you are following along the course, you need to change the cache folder to --cache /data/.vep or VEP will not find the local cache.
Exercise 1
ImportantBasic VEP Analysis
Objective: Annotate a small VCF file and understand the basic output format.
Input Data:
##fileformat=VCFv4.2
#CHROM POS ID REF ALT QUAL FILTER INFO
chr7 55242465 rs121913529 A T . PASS .
chr17 7577121 rs28934578 C T . PASS .
chr13 32936646 rs28897743 C T . PASS .
chr17 7674894 rs28934574 G A . PASS .
chr13 32914438 rs80357090 T C . PASS .
chr17 41245466 rs28897686 G A . PASS .
chr3 178936091 rs63751289 G A . PASS .
chr10 89624230 rs61751507 G A . PASS .
chr11 108098576 rs386833395 G A . PASS .
chr4 55141055 rs1800744 A G . PASS .
chr1 11190510 rs6603781 G A . PASS .
chr7 140453136 rs121913530 A T . PASS .
chr5 112175770 rs121913343 C T . PASS .
chr17 43094464 rs28897672 A C . PASS .
Task: Annotate these variants using VEP and identify which genes are affected.
NoteCommand
VEP can be provided with a VCF file as an input (or vcf.gz + index) file or other formats, see documentation here
vep-i cancer_variants.vcf \--cache /data/.vep \--species homo_sapiens \--assembly GRCh38 \--offline --format vcf \--symbol \--force_overwrite \--domains \--sift b \--polyphen b \--output_file output.txt
TipSolution
# 0. from your terminal go to your project foldercd ~/project# 1. First, create a script that will generate our VCF file. # Copy this code (from #!/usr/bin/env bash) into a new file named `create_vcf.sh`# with the command `nano create_vcf.sh`:#!/usr/bin/env bashecho-e'##fileformat=VCFv4.2##INFO=<ID=AF,Number=A,Type=Float,Description="Allele Frequency">#CHROM\tPOS\tID\tREF\tALT\tQUAL\tFILTER\tINFOchr7\t55242465\trs121913529\tA\tT\t.\tPASS\t.chr17\t7577121\trs28934578\tC\tT\t.\tPASS\t.chr13\t32936646\trs28897743\tC\tT\t.\tPASS\t.chr17\t7674894\trs28934574\tG\tA\t.\tPASS\t.chr13\t32914438\trs80357090\tT\tC\t.\tPASS\t.chr17\t41245466\trs28897686\tG\tA\t.\tPASS\t.chr3\t178936091\trs63751289\tG\tA\t.\tPASS\t.chr10\t89624230\trs61751507\tG\tA\t.\tPASS\t.chr11\t108098576\trs386833395\tG\tA\t.\tPASS\t.chr4\t55141055\trs1800744\tA\tG\t.\tPASS\t.chr1\t11190510\trs6603781\tG\tA\t.\tPASS\t.chr7\t140453136\trs121913530\tA\tT\t.\tPASS\t.chr17\t43094464\trs28897672\tA\tC\t.\tPASS\t.chr5\t112175770\trs121913343\tC\tT\t.\tPASS\t.'> cancer_variants.vcf# 2. Make the script executable:chmod +x create_vcf.sh# 3. Run the script:./create_vcf.sh# 4. Verify the file was created correctly:# Check the contentcat cancer_variants.vcf# Make sure you have 13 variantsgrep-v'^#' cancer_variants.vcf |wc-l# it should show 14# Run VEP ~< 5minvep-i cancer_variants.vcf \--cache /data/.vep \--species homo_sapiens \--offline\--force_overwrite\--assembly GRCh38 \--format vcf \--symbol\--sift b \--polyphen b \--pick\--domains\--output_file output.txt# Some of the variants affect:## VEP command-line: vep --assembly GRCh38 --cache /data/.vep --database 0 --force_overwrite --format vcf --input_file cancer_variants.vcf --offline --output_file output.txt --pick --symbol#Uploaded_variation Location Allele Gene Feature Feature_type Consequence cDNA_position CDS_position Protein_position Amino_acids Codons Existing_variation Extrars121913529 chr7:55242465 T ENSG00000280890 ENST00000626532 Transcript intron_variant,non_coding_transcript_variant ------ IMPACT=MODIFIER;STRAND=-1;SYMBOL=ELDR;SYMBOL_SOURCE=HGNC;HGNC_ID=HGNC:49511rs28934578 chr17:7577121 T ENSG00000161960 ENST00000293831 Transcript missense_variant 597 580 194 D/Y Gac/Tac - IMPACT=MODERATE;STRAND=1;SYMBOL=EIF4A1;SYMBOL_SOURCE=HGNC;HGNC_ID=HGNC:3282rs28897743 chr13:32936646 T --- intergenic_variant ------ IMPACT=MODIFIERrs28934574 chr17:7674894 A ENSG00000141510 ENST00000269305 Transcript stop_gained 779 637 213 R/* Cga/Tga - IMPACT=HIGH;STRAND=-1;SYMBOL=TP53;SYMBOL_SOURCE=HGNC;HGNC_ID=HGNC:11998rs28897686 chr17:41245466 A ENSG00000241595 ENST00000334109 Transcript upstream_gene_variant ------ IMPACT=MODIFIER;DISTANCE=4221;STRAND=1;SYMBOL=KRTAP9-4;SYMBOL_SOURCE=HGNC;HGNC_ID=HGNC:18902
rs28934574 from this example is a TP53 stop gained mutation commonly found in cancer.
You can try to run without --pick and --everything see what happens.
After running the command you will also notice a output.txt_summary.html that will show some statistics on the annotation process and the results visually (see solution above). If you tried running --everything or -e this is a shortcut for the following options:
This an example of the highput from the TP53 mutation
Field
Value
Description
Uploaded Variation
rs28934574
dbSNP identifier
Location
chr17:7674894
Genomic coordinates (GRCh38)
Allele
A
Alternative allele
Gene
ENSG00000141510
Ensembl gene ID for TP53
Transcript
ENST00000455263
Ensembl transcript ID
Feature Type
Transcript
Type of genomic feature affected
Consequence
stop_gained
Creates premature stop codon
cDNA Position
770
Position in the cDNA
CDS Position
637
Position in the coding sequence
Protein Position
213
Position in the protein
Amino Acids
R/*
Change from Arginine to stop codon
Codons
Cga/Tga
Codon change
Impact
HIGH
Severity of variant impact
Symbol
TP53
HGNC gene symbol
Biotype
protein_coding
Type of transcript
CCDS
CCDS45605.1
Consensus CDS identifier
UniProt
P04637.305
UniProt protein identifier
HGVSc
ENST00000455263.6:c.637C>T
Coding sequence change in HGVS notation
HGVSp
ENSP00000398846.2:p.Arg213Ter
Protein change in HGVS notation
Clinical Significance
pathogenic
Clinical interpretation
gnomAD AF
1.368e-06
Allele frequency in gnomAD
Maximum AF
1.656e-05
Maximum allele frequency observed
You can have a look at the documentation to learn more about VEP’s many options here
NoteDamage prediction tools
SIFT (Sorting Intolerant From Tolerant) and PolyPhen (Polymorphism Phenotyping) are both prediction tools specifically designed to assess the functional impact of missense variants—those that result in amino acid substitutions
SIFT: Based on sequence homology and physical properties of amino acids
PolyPhen: Combines sequence-based features with structural information
Mutect2 results annotation
The previous section demonstrated how to run VEP and how different arguments significantly impact the output. Now, let’s apply this to a real dataset. We will take the table of somatic variants identified from the WES of chr6 and chr17 and use VEP to enrich it with functional annotations.
Extract from the resulting Mutect2 somatic call
##fileformat=VCFv4.2
#CHROM POS ID REF ALT QUAL FILTER INFO
chr17 745040 . G T . PASS
chr17 1492466 . C T . PASS
chr17 2364457 . T G . PASS
chr17 3433669 . G T . PASS
chr17 4545725 . T C . PASS
chr17 4934441 . G T . PASS
chr17 5007047 . C T . PASS
chr17 7560755 . G A . PASS
chr17 7588500 . G C . PASS
chr6 325357 . G A . PASS
chr6 325783 . G C . PASS
chr6 325901 . G A . PASS
chr6 1916336 . G A . PASS
chr6 2674999 . A C . PASS
chr6 2834013 . C G . PASS
chr6 2840548 . C T . PASS
chr6 3723708 . C G . PASS
Using VEP to annotate Mutect2 variants
The somatic variant call can be annotated with this command
We are using as input a vcf.gz file (which has been indexed), and we are provifing the --format vcf command, this will output by default a tsv file
Exercise 2
ImportantOutput to VCF
What if the output of this file should be formatted as vcf instead? You can check VEP’s documentation here hint: use --vcf
TipSolution
With the option --output_file you can use vcf. After you can compress the VCF bgzip <output_file.vcf> and then you can index it tabix -p vcf <output_file.vcf.gz>. If you see VEP’s documentation there is an option to skip bgzip and instead incorporating it directly in VEP, which will be doing the compression for you --compress_output bgzip in the call. Afterwards you still need to index the file.
Interesting results: We will obtain a file with many annotations.
Now when we anaylize our output file chr6ch17_mutect2_annotated.txt in more details, there are about 160 lines and a lot of information on different transcripts that are related to the mutations found by Mutect2. Let’s say that now we would like to filter only the deleterious predictions and moderate/high impact variants. We can do that in a couple of ways:
filter_vep\-i chr6ch17_mutect2_annotated.txt \-o chr6ch17_mutect2_annotated_filtered.txt \--force_overwrite \--filter "(IMPACT is HIGH or IMPACT is MODERATE) or (SIFT match deleterious or PolyPhen match probably_damaging)"
Caution
in this line --filter "(IMPACT is HIGH or IMPACT is MODERATE) or (SIFT match deleterious or PolyPhen match probably_damaging)" consider that there is a difference in saying or or and as the latter is much more stringent and it would look only for variants whose prediction is in agreement.
But what if we want more information on the cancer mutations, can we integrate other databases to VEP? Yes we can. This can be useful prior to filtering to find additional consensus on potential interesting targets.
Exercise 3
ImportantCancer-Specific Annotation
Objective: Add cancer-specific annotations using ClinVar and filter for potentially pathogenic variants.
# Download ClinVar VCFVARIANTDIR="${HOME}/project/course_data/variants"RESOURCEDIR="${HOME}/project/course_data/VEP_dbs"# Run VEP with cancer-specific annotationsvep-i"$VARIANTDIR/somatic.filtered.PASS.vcf.gz"\--cache /data/.vep \--assembly GRCh38 \--format vcf \--force_overwrite\--fork 2 \--everything\--custom"$RESOURCEDIR"/clinvar/clinvar.vcf.gz,ClinVar,vcf,exact,0,CLNSIG,CLNREVSTAT,CLNDN \--output_file"$VARIANTDIR/chr6ch17_mutect2_annotated_with_clinVar.txt"# Filter resultsfilter_vep\-i "$VARIANTDIR/chr6ch17_mutect2_annotated_with_clinVar.txt"\-o "$VARIANTDIR/chr6ch17_mutect2_annotated_with_clinVar_filtered.txt"\--force_overwrite \--filter "(IMPACT is HIGH or IMPACT is MODERATE) or \(SIFT match deleterious or PolyPhen match probably_damaging) or \(ClinVar_CLNSIG match pathogenic)"# Generate summary (using simple grep/awk commands)echo"Mutation Type Summary:"> summary.txtgrep-v"#""$VARIANTDIR/chr6ch17_mutect2_annotated_with_clinVar_filtered.txt"|cut-f7|sort|uniq-c>>"$VARIANTDIR/summary_chr6ch17_mutect2_annotated_with_clinVar_filtered.txt"
The possible values for ClinVar_CLNSIG include:
Pathogenic - Strong evidence the variant causes disease
Likely_pathogenic - Evidence suggests it is probably disease-causing
Uncertain_significance (VUS) - Not enough evidence to classify either way
Likely_benign - Evidence suggests it is probably not disease-causing
Benign - Strong evidence the variant is not disease-causing
Conflicting_interpretations_of_pathogenicity - Different submitters disagree
Not_provided - No interpretation was provided
Drug_response - Affects response to medications
Other - Other interpretations
The clinvar data provided us with more information coming from curated databases, and for some variants we can have multiple levels of consensus (however this is not a garantee of pathogenicity), but there are many other additional databases that one can try. However not all the databases have the same licensing, therefore each of the integrated datasets should be checked. For example COSMIC databases can be accessed only after registration, onkoKB as well.
Note
Please do not forget to cite the data that you use and it is important to keep note of the version used. This is also an essential information for your future you!
Advanced Topics
Using VEP Plugins
VEP’s functionality can be extended through plugins. Here are some essential plugins for cancer analysis:
REVEL: Rare Exome Variant Ensemble Learner
REVEL paper: An Ensemble Method for Predicting the Pathogenicity of Rare Missense Variants
We have seen how to run VEP and how to filter the output. Now we can make another call on the Mutect2 output to annotate the variants using a combination of some plugins and some custom databases.
NoteDamage prediction tools
REVEL: An ensemble method that integrates multiple prediction tools
AlphaMissense: Uses deep learning trained on evolutionary data
ClinVar: Provides clinical interpretations from expert curation
Complex VEP annotation
Here we learn how to use additional data to include additional information to the annotation
Exercise 4
ImportantComplex VEP run
Objective: Learn how to comprehensively annotate cancer variants using VEP’s advanced features, plugins, and filtering capabilities to identify potentially pathogenic variants.
VARIANTDIR="${HOME}/project/course_data/variants"RESOURCEDIR="${HOME}/project/course_data/VEP_dbs"vep-i"$VARIANTDIR/somatic.filtered.PASS.vcf.gz"\--cache /data/.vep \--assembly GRCh38 \--format vcf \--fork 2 \--everything\--af_gnomade\--force_overwrite\--plugin SpliceRegion \--plugin REVEL,file="$RESOURCEDIR/revel/new_tabbed_revel_grch38.tsv.gz"\--plugin AlphaMissense,file="$RESOURCEDIR/alphamissense/AlphaMissense_hg38.tsv.gz"\--custom"$RESOURCEDIR/clinvar/clinvar.vcf.gz",ClinVar,vcf,overlap,0,CLNSIG,CLNREVSTAT,CLNDN \--output_file"$VARIANTDIR/chr6ch17_mutect2_annotated_with_clinVar_and_plugins.txt"# Filter the data -> Stringentfilter_vep\-i "$VARIANTDIR/chr6ch17_mutect2_annotated_with_clinVar_and_plugins.txt"\-o "$VARIANTDIR/stringent_filtered.txt"\--force_overwrite \--filter "(IMPACT is HIGH or IMPACT is MODERATE) and \ (REVEL >= 0.75 or \ am_class = 'likely_pathogenic' or \ SIFT = 'deleterious' and PolyPhen = 'probably_damaging')"# Filter the data -> Moderatefilter_vep\-i "$VARIANTDIR/chr6ch17_mutect2_annotated_with_clinVar_and_plugins.txt"\-o "$VARIANTDIR/moderate_filtered.txt"\--force_overwrite \--filter "(IMPACT is HIGH or IMPACT is MODERATE) and \ (REVEL >= 0.5 or \ am_class = 'likely_pathogenic' or \ SIFT = 'deleterious' or \ PolyPhen = 'probably_damaging')"
REVEL score: 0.884 (>0.5 considered possibly pathogenic)
AlphaMissense:
Class: likely_pathogenic
Pathogenicity score: 0.9946 (very high confidence)
SpliceRegion: No splice site effects detected
ClinVar: No clinical data found in ClinVar database
SIF: SIFT=deleterious(0)
PolyPhen: PolyPhe=probably_damaging(1)
IMPACT: MODERATE
Additional Annotations
Feature
Value
Description
COSMIC ID
COSV57568710
Catalogued in COSMIC database
Somatic Status
SOMATIC=1
Confirmed somatic variant
Phenotype
PHENO=1
Associated with phenotype
UniProt
P20794.202
Protein database reference
Note
At this point we obtained a good annotated set of somatic variants. This paves the way for further analysis. For example you can add more databases to your annotation call, such as COSMIC, cancerhotspots, onkoKB etc. You can also try other plugins, depending on your biological question(s). Those can add addtional data ond possibly additional filtering options.
Add other databases
Try additional plugins
Find interesting genes that could be drivers in your samples
Consider population frequency of the mutation(s) (common variants are less likely to be pathogenic)
Consider possible drug-gene interactions
Check in the literature
Visualize the results
NoteAdvanced Topic: Annotating CNVs with VEP
CNV annotation is more challenging than SNV annotation because:
Tools like REVEL/AlphaMissense are designed for SNVs
CNV breakpoints can be imprecise
Functional impact affects multiple genes
For those interested in CNV annotation, expanded materials are available in the advanced resources section.
Let’s visualize some of the data from our somatic call annotation!
At first we should load one of the vep annotated files from one of the exercises. Let’s load the results from exercise 3 (feel free to load another one!), chr6ch17_mutect2_annotated_with_clinVar.txt from the exercise Cancer-Specific Annotation.
Code
# get librarieslibrary(tidyverse)library(magrittr)library(readr)# VEP output invep_data <-read_tsv("scripts/variant_annotation/chr6ch17_mutect2_annotated_with_clinVar.txt",comment ="##")# better to set up a ggplot2 themetheme_course <-function() {theme_minimal(base_size =14) +# Base size affects all texttheme(plot.title =element_text(size =16, face ="bold"),axis.title =element_text(size =14, face ="bold"),axis.text =element_text(size =12),legend.title =element_text(size =13, face ="bold"),legend.text =element_text(size =12),strip.text =element_text(size =13, face ="bold"), # For facetslegend.position ="bottom" )}# Split when it contains multiple valuesconsequences_df <- vep_data %>%separate_rows(Consequence, sep="&") %>%select(Consequence)# get chrvep_data <- vep_data %>%separate(Location, into =c("chr", "position"), sep=":") %>%mutate(chr =factor(chr, levels =c("chr6", "chr17")))# Extract IMPACT from Extra columnvep_data$IMPACT <-gsub(".*IMPACT=([^;]+).*", "\\1", vep_data$Extra)# get nice data out of the dfextract_field <-function(data, field) {gsub(paste0(".*", field, "=([^;]+).*"), "\\1", data$Extra)}# combine multiple fieldsvep_data <- vep_data %>%mutate(IMPACT =extract_field(., "IMPACT"),SYMBOL =extract_field(., "SYMBOL"),VARIANT_CLASS =extract_field(., "VARIANT_CLASS"),BIOTYPE =extract_field(., "BIOTYPE") )
Exercise 5
ImportantVisualize the data from VEP
Objective: Learn how to quickly visualize your variants.
Task: Visualize:
Consequence plot, to visualize the distribution of consequences?
Consequence plot, by chromosome?
Can we see the consequence colored by impact?
Can we see the consequence colored by impact by chromosome?
What are the most common variant classes?
What are the most common biotypes?
Bonus: ClinVar, SIFT, and PolyPhen
Bonus: Gene level damage
Tip1. Consequence plot, to visualize the distribution of consequences
For COSMIC: We cannot provide those files (they require licensing), you need to register and download the files. CosmicMutantExport.tsv.gz You can register here:
Best Practices from Literature
NoteKey Recommendations
From McLaren et al. (2016) - VEP Paper:
Use --pick or --per_gene to manage transcript complexity
Combine multiple prediction algorithms for consensus
Always document VEP version and cache version for reproducibility
For Cancer Analysis:
Filter common variants (gnomAD MAF < 0.01) for somatic analysis
Consider tissue-specific expression data when available
Use multiple evidence sources (ClinVar + COSMIC + literature)
Validate high-priority variants with orthogonal methods
Figure 1: Image from the 
