Variant Effect Predictor Custom annotations

VEP can integrate custom annotation from standard format files into your results by using the --custom flag.

These files may be hosted locally or remotely, with no limit to the number or size of the files. The files must be indexed using the tabix utility (BED, GFF, GTF, VCF); bigWig files contain their own indices.

Annotations typically appear as key=value pairs in the Extra column of the VEP output; they will also appear in the INFO column if using VCF format output. The value for a particular annotation is defined as the identifier for each feature; if not available, an identifier derived from the coordinates of the annotation is used. Annotations will appear in each line of output for the variant where multiple lines exist.

Data formats

VEP supports the following annotation formats:

Any other files can be easily converted to be compatible with VEP; the easiest format to produce is a BED-like file containing coordinates and an (optional) identifier:

chr1    10000    11000    Feature1
chr3    25000    26000    Feature2
chrX    99000    99001    Feature3

Chromosomes can be denoted by either e.g. "chr7" or "7", "chrX" or "X".

Preparing files

Custom annotation files must be prepared in a particular way in order to work with tabix and therefore with VEP. Files must be stripped of comment lines, sorted in chromosome and position order, compressed using bgzip and finally indexed using tabix. Here are some examples of that process for:

• GFF file

  grep -v "#" myData.gff | sort -k1,1 -k4,4n -k5,5n -t$'\t' | bgzip -c > myData.gff.gz
  tabix -p gff myData.gff.gz

  Note

  VEP expects few extra fields in the 9th column of the GFF file. See the extra fields list.
• BED file

  grep -v "#" myData.bed | sort -k1,1 -k2,2n -k3,3n -t$'\t' | bgzip -c > myData.bed.gz
  tabix -p bed myData.bed.gz

The tabix utility has several preset filetypes that it can process, and it can also process any arbitrary filetype containing at least a chromosome and position column. See the documentation for details.

If you are going to use the file remotely (i.e. over HTTP or FTP protocol), you should ensure the file is world-readable on your server.

Options

Using positional options in --custom with VEP 109 and earlier (compatible with VEP 113)

./vep [...] --custom Filename,Short_name,File_type,Annotation_type,Force_report_coordinates,VCF_fields

    # BigWig file
    ./vep [...] --custom frequencies.bw,Frequency,bigwig,exact,0
    # BED file
    ./vep [...] --custom http://www.myserver.com/data/myPhenotypes.bed.gz,Phenotype,bed,exact,1
    # VCF file
    ./vep [...] --custom https://ftp.ensembl.org/pub/grch37/data_files/homo_sapiens/GRCh37/variation_genotype/TOPMED_GRCh37.vcf.gz,,vcf,exact,0,TOPMED

    # For multiple custom files, use:
    ./vep [...] --custom clinvar.vcf.gz,ClinVar,vcf,exact,0,CLNSIG,CLNREVSTAT,CLNDN \
                --custom TOPMED_GRCh38_20180418.vcf.gz,topmed_20180418,vcf,exact,0,TOPMED \
                --custom UK10K_COHORT.20160215.sites.GRCh38.vcf.gz,uk10k,vcf,exact,0,AF_ALSPAC

Using key-value pairs in --custom with VEP 113

./vep [...] --custom file=Filename,short_name=Short_name,format=File_type,type=Annotation_type,fields=VCF_fields

file

format

short_name

fields

type

overlap_cutoff

reciprocal

distance

coords

same_type

num_records

summary_stats

# BigWig file
./vep [...] --custom file=frequencies.bw,short_name=Frequency,format=bigwig,type=exact,coords=0
# BED file
./vep [...] --custom file=http://www.myserver.com/data/myPhenotypes.bed.gz,short_name=Phenotype,format=bed,type=exact,coords=1
# VCF file
./vep [...] --custom file=https://ftp.ensembl.org/pub/grch37/data_files/homo_sapiens/GRCh37/variation_genotype/TOPMED_GRCh37.vcf.gz,format=vcf,type=exact,coords=0,fields=TOPMED
./vep [...] --custom file=gnomad_v2.1_sv.sites.vcf.gz,short_name=gnomad,fields=PC%EVIDENCE%SVTYPE,format=vcf,type=within,reciprocal=1,overlap_cutoff=80

# For multiple custom files, use:
./vep [...] --custom file=clinvar.vcf.gz,short_name=ClinVar,format=vcf,type=exact,coords=0,fields=CLNSIG%CLNREVSTAT%CLNDN \
            --custom file=TOPMED_GRCh38_20180418.vcf.gz,short_name=topmed_20180418,format=vcf,type=exact,coords=0,fields=TOPMED \
            --custom file=UK10K_COHORT.20160215.sites.GRCh38.vcf.gz,short_name=uk10k,format=vcf,type=exact,coords=0,fields=AF_ALSPAC

Example - ClinVar

We include the most recent public variant and phenotype data available in each Ensembl release, but some projects release data more frequently than we do.
If you want to have the very latest annotations, you can use the data files from your prefered projects (in any format listed in Data formats) and use them as a VEP custom annotation.

For instance, you can annotate you variants with VEP, using the the latest ClinVar data as custom annotation.
ClinVar provides VCF files on their FTP site: GRCh37 and GRCh38.

See below an example about how to use ClinVar VCF files as a VEP custom annotation:

1. Download the VCF files (you need the compressed VCF file and the index file), e.g.:

   # Compressed VCF file
   curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz
   # Index file
   curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz.tbi

2. Example of command you can use:

   ./vep [...] --custom file=clinvar.vcf.gz,short_name=ClinVar,format=vcf,type=exact,coords=0,fields=CLNSIG%CLNREVSTAT%CLNDN
   
   ## Where the selected ClinVar INFO fields (from the ClinVar VCF file) are:
   # - CLNSIG:     Clinical significance for this single variant
   # - CLNREVSTAT: ClinVar review status for the Variation ID
   # - CLNDN:      ClinVar's preferred disease name for the concept specified by disease identifiers in CLNDISDB
   # Of course you can select the INFO fields you want in the ClinVar VCF file
   
   # Quick example on GRCh38:
   ./vep --id "1  230710048 230710048 A/G 1" --species homo_sapiens -o /path/to/output/output.txt --cache --offline --assembly GRCh38 --custom file=/path/to/custom_files/clinvar.vcf.gz,short_name=ClinVar,format=vcf,type=exact,coords=0,fields=CLNSIG%CLNREVSTAT%CLNDN

   Results in the default VEP format

   ## Column descriptions:
   ## Uploaded_variation : Identifier of uploaded variant
   ## Location : Location of variant in standard coordinate format (chr:start or chr:start-end)
   ## Allele : The variant allele used to calculate the consequence
   ## Gene : Stable ID of affected gene
   ## Feature : Stable ID of feature
   ## Feature_type : Type of feature - Transcript, RegulatoryFeature or MotifFeature
   ## Consequence : Consequence type
   ## cDNA_position : Relative position of base pair in cDNA sequence
   ## CDS_position : Relative position of base pair in coding sequence
   ## Protein_position : Relative position of amino acid in protein
   ## Amino_acids : Reference and variant amino acids
   ## Codons : Reference and variant codon sequence
   ## Existing_variation : Identifier(s) of co-located known variants
   ## Extra column keys:
   ## IMPACT : Subjective impact classification of consequence type
   ## DISTANCE : Shortest distance from variant to transcript
   ## STRAND : Strand of the feature (1/-1)
   ## FLAGS : Transcript quality flags
   ## SOURCE : Source of transcript
   ## ClinVar : /opt/vep/.vep/custom/clinvar.vcf.gz (exact)
   ## ClinVar_CLNSIG : CLNSIG field from /path/to/custom_files/clinvar.vcf.gz
   ## ClinVar_CLNREVSTAT : CLNREVSTAT field from /path/to/custom_files/clinvar.vcf.gz
   ## ClinVar_CLNDN : CLNDN field from /path/to/custom_files/clinvar.vcf.gz
   #Uploaded_variation  Location     Allele  Gene             Feature          Feature_type  Consequence              ...  Extra
   1_230710048_A/G      1:230710048  G       ENSG00000135744  ENST00000366667  Transcript    missense_variant         ...  IMPACT=MODERATE;STRAND=-1;ClinVar=18068;ClinVar_CLNDN=Hypertension,_essential,_susceptibility_to|Preeclampsia,_susceptibility_to|Renal_dysplasia|Susceptibility_to_progression_to_renal_failure_in_IgA_nephropathy|not_specified;ClinVar_CLNREVSTAT=criteria_provided,_multiple_submitters,_no_conflicts;ClinVar_CLNSIG=Benign;ClinVar_FILTER=.
   1_230710048_A/G      1:230710048  G       ENSG00000244137  ENST00000412344  Transcript    downstream_gene_variant  ...  IMPACT=MODIFIER;DISTANCE=650;STRAND=-1;ClinVar=18068;ClinVar_CLNDN=Hypertension,_essential,_susceptibility_to|Preeclampsia,_susceptibility_to|Renal_dysplasia|Susceptibility_to_progression_to_renal_failure_in_IgA_nephropathy|not_specified;ClinVar_CLNREVSTAT=criteria_provided,_multiple_submitters,_no_conflicts;ClinVar_CLNSIG=Benign;ClinVar_FILTER=.

   Results in VCF (adding the tag --vcf in the command line)

   ##fileformat=VCFv4.1
   ##INFO=<ID=CSQ,Number=.,Type=String,Description="Consequence annotations from Ensembl VEP. Format: Allele|Consequence|IMPACT|SYMBOL|Gene|Feature_type|Feature|BIOTYPE|EXON|INTRON|HGVSc|HGVSp|cDNA_position|CDS_position|Protein_position|Amino_acids|Codons|Existing_variation|DISTANCE|STRAND|FLAGS|SYMBOL_SOURCE|HGNC_ID|SOURCE|ClinVar|ClinVar_CLNSIG|ClinVar_CLNREVSTAT|ClinVar_CLNDN">
   ##INFO=<ID=ClinVar,Number=.,Type=String,Description="/path/to/custom_files/clinvar.vcf.gz (exact)">
   ##INFO=<ID=ClinVar_CLNSIG,Number=.,Type=String,Description="CLNSIG field from /path/to/custom_files/clinvar.vcf.gz">
   ##INFO=<ID=ClinVar_CLNREVSTAT,Number=.,Type=String,Description="CLNREVSTAT field from /path/to/custom_files/clinvar.vcf.gz">
   ##INFO=<ID=ClinVar_CLNDN,Number=.,Type=String,Description="CLNDN field from /path/to/custom_files/clinvar.vcf.gz">
   #CHROM  POS        ID               REF  ALT  QUAL  FILTER  INFO
   1       230710048  1_230710048_A/G  A    G    .     .       CSQ=G|missense_variant|MODERATE|AGT|ENSG00000135744|Transcript|ENST00000366667|protein_coding|2/5||||1018|803|268|M/T|aTg/aCg|||-1||HGNC|HGNC:333||18068|Benign|criteria_provided&_multiple_submitters&_no_conflicts|Hypertension&_essential&_susceptibility_to&Preeclampsia&_susceptibility_to&Renal_dysplasia&Susceptibility_to_progression_to_renal_failure_in_IgA_nephropathy¬_specified,G|downstream_gene_variant|MODIFIER|AL512328.1|ENSG00000244137|Transcript|ENST00000412344|antisense|||||||||||650|-1||Clone_based_ensembl_gene|||18068|Benign|criteria_provided&_multiple_submitters&_no_conflicts|Hypertension&_essential&_susceptibility_to&Preeclampsia&_susceptibility_to&Renal_dysplasia&Susceptibility_to_progression_to_renal_failure_in_IgA_nephropathy&not_specified

Using remote files

The tabix utility makes it possible to read annotation files from remote locations, for example over HTTP or FTP protocols.

In order to do this, the .tbi index file is downloaded locally (to the current working directory) when VEP is run. From this point on, only the portions of data requested by VEP (i.e. those overlapping the variants in your input file) are downloaded.

bigWig files can also be used remotely in the same way as tabix-indexed files, although less stringent checks are carried out on VEP startup.

Example - phyloP and phastCons conservation scores

The UCSC Genome Browser provides multiple alignment files with phyloP and phastCons conservation scores for different genomes in the BigWig (.bw) format.

These files can be remotely used as VEP custom annotations by simply pointing to their URL. For instance, to include phyloP or phastCons 100 way conservation scores found in the Downloads section of the UCSC Genome Browser, you can use commands such as:

# Human GRCh38/hg38 phyloP100way scores
./vep [...] --custom file=http://hgdownload.soe.ucsc.edu/goldenPath/hg38/phyloP100way/hg38.phyloP100way.bw,short_name=phyloP100way,format=bigwig

# Human GRCh38/hg38 phastCons100way scores
./vep [...] --custom file=http://hgdownload.soe.ucsc.edu/goldenPath/hg38/phastCons100way/hg38.phastCons100way.bw,short_name=phastCons100way,format=bigwig