# ensemblVEP: using the REST API with Bioconductor

# Introduction

Ensembl’s Variant Effect Predictor is described in McLaren et al. (2016).

Prior to Bioconductor 3.19, the ensemblVEP package provided access to Ensembl’s predictions through an interface between Perl and MySQL.

In 3.19 VariantAnnotation supports the use of the VEP component of the REST API at https://rest.ensembl.org.

# Acquire annotation on variants from a VCF file

The function `vep_by_region` will accept a VCF object as defined in VariantAnnotation.

    library(VariantAnnotation)
    fl <- system.file("extdata", "chr22.vcf.gz", package="VariantAnnotation")
    r22 = readVcf(fl)
    r22

    ## class: CollapsedVCF
    ## dim: 10376 5
    ## rowRanges(vcf):
    ##   GRanges with 5 metadata columns: paramRangeID, REF, ALT, QUAL, FILTER
    ## info(vcf):
    ##   DataFrame with 22 columns: LDAF, AVGPOST, RSQ, ERATE, THETA, CIEND, CIPOS,...
    ## info(header(vcf)):
    ##              Number Type    Description
    ##    LDAF      1      Float   MLE Allele Frequency Accounting for LD
    ##    AVGPOST   1      Float   Average posterior probability from MaCH/Thunder
    ##    RSQ       1      Float   Genotype imputation quality from MaCH/Thunder
    ##    ERATE     1      Float   Per-marker Mutation rate from MaCH/Thunder
    ##    THETA     1      Float   Per-marker Transition rate from MaCH/Thunder
    ##    CIEND     2      Integer Confidence interval around END for imprecise var...
    ##    CIPOS     2      Integer Confidence interval around POS for imprecise var...
    ##    END       1      Integer End position of the variant described in this re...
    ##    HOMLEN    .      Integer Length of base pair identical micro-homology at ...
    ##    HOMSEQ    .      String  Sequence of base pair identical micro-homology a...
    ##    SVLEN     1      Integer Difference in length between REF and ALT alleles
    ##    SVTYPE    1      String  Type of structural variant
    ##    AC        .      Integer Alternate Allele Count
    ##    AN        1      Integer Total Allele Count
    ##    AA        1      String  Ancestral Allele, ftp://ftp.1000genomes.ebi.ac.u...
    ##    AF        1      Float   Global Allele Frequency based on AC/AN
    ##    AMR_AF    1      Float   Allele Frequency for samples from AMR based on A...
    ##    ASN_AF    1      Float   Allele Frequency for samples from ASN based on A...
    ##    AFR_AF    1      Float   Allele Frequency for samples from AFR based on A...
    ##    EUR_AF    1      Float   Allele Frequency for samples from EUR based on A...
    ##    VT        1      String  indicates what type of variant the line represents
    ##    SNPSOURCE .      String  indicates if a snp was called when analysing the...
    ## geno(vcf):
    ##   List of length 3: GT, DS, GL
    ## geno(header(vcf)):
    ##       Number Type   Description
    ##    GT 1      String Genotype
    ##    DS 1      Float  Genotype dosage from MaCH/Thunder
    ##    GL G      Float  Genotype Likelihoods

In this example we confine attention to single nucleotide variants.

There is a limit of 200 locations in a request, and 55000 requests per hour. We’ll base our query on 100 positions in the chr22 VCF.

    dr = which(width(rowRanges(r22))!=1)
    r22s = r22[-dr]
    res = vep_by_region(r22[1:100], snv_only=FALSE, chk_max=FALSE)
    jans = toJSON(content(res))

There are various ways to work with the result of this query to the API. We’ll use the rjsoncons JSON processing infrastructure to dig in and understand aspects of the API behavior.

First, the top-level concepts produced for each variant can be retrieved using

    library(rjsoncons)
    names(jsonlite::fromJSON(jmespath(jans, "[*]")))

    ##  [1] "input"                           "seq_region_name"
    ##  [3] "id"                              "start"
    ##  [5] "assembly_name"                   "most_severe_consequence"
    ##  [7] "allele_string"                   "end"
    ##  [9] "strand"                          "transcript_consequences"
    ## [11] "colocated_variants"              "regulatory_feature_consequences"

Annotation of the most severe consequence known will typically be of interest:

    table(jsonlite::fromJSON(jmespath(jans, "[*].most_severe_consequence")))

    ##
    ##   5_prime_UTR_variant        intron_variant splice_region_variant
    ##                    22                    76                     2

There is variability in the structure of data returned for each query.

    head(fromJSON(jmespath(jans, "[*].regulatory_feature_consequences")))

    ## [[1]]
    ##   consequence_terms regulatory_feature_id variant_allele      biotype   impact
    ## 1      regulato....          ENSR22_5....              T CTCF_bin.... MODIFIER

Furthermore, the content of the motif feature consequences field seems very peculiar.

    table(unlist(fromJSON(jmespath(jans, "[*].motif_feature_consequences"))))

    ## < table of extent 0 >

# Transforming the API response to GRanges

We’ll consider the following approach to converting the API response to a GenomicRanges GRanges instance. Eventually this may become part of the package.

    library(GenomicRanges)
    .make_GRanges = function( vep_response ) {
      stopifnot(inherits(vep_response, "response"))  # httr
      nested = fromJSON(toJSON(content(vep_response)))
      ini = GRanges(seqnames = unlist(nested$seq_region_name),
        IRanges(start=unlist(nested$start), end=unlist(nested$end)))
      dr = match(c("seq_region_name", "start", "end"), names(nested))
      mcols(ini) = DataFrame(nested[,-dr])
      ini
    }
    tstg = .make_GRanges( res )
    tstg[,1]  # full print is unwieldy

    ## GRanges object with 100 ranges and 1 metadata column:
    ##         seqnames    ranges strand |                  input
    ##            <Rle> <IRanges>  <Rle> |                 <list>
    ##     [1]       22  50300078      * | 22 50300078 rs741029..
    ##     [2]       22  50300086      * | 22 50300086 rs147922..
    ##     [3]       22  50300101      * | 22 50300101 rs114143..
    ##     [4]       22  50300113      * | 22 50300113 rs141778..
    ##     [5]       22  50300166      * | 22 50300166 rs182170..
    ##     ...      ...       ...    ... .                    ...
    ##    [96]       22  50304748      * | 22 50304748 rs141641..
    ##    [97]       22  50304805      * | 22 50304805 rs761151..
    ##    [98]       22  50304935      * | 22 50304935 rs121677..
    ##    [99]       22  50304943      * | 22 50304943 rs186556..
    ##   [100]       22  50305084      * | 22 50305084 rs116244..
    ##   -------
    ##   seqinfo: 1 sequence from an unspecified genome; no seqlengths

    names(mcols(tstg))

    ## [1] "input"                           "id"
    ## [3] "assembly_name"                   "most_severe_consequence"
    ## [5] "allele_string"                   "strand"
    ## [7] "transcript_consequences"         "colocated_variants"
    ## [9] "regulatory_feature_consequences"

Now information about variants can be retrieved with range operations. Deep annotation requires nested structure of the metadata columns.

    mcols(tstg)[1, "transcript_consequences"]

    ## [[1]]
    ##         gene_id gene_symbol strand   hgnc_id consequence_terms variant_allele
    ## 1  ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 2  ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 3  ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 4  ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 5  ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 6  ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 7  ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 8  ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 9  ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 10 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 11 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 12 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 13 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 14 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 15 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 16 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 17 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 18 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 19 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 20 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 21 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 22 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 23 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 24 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 25 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ## 26 ENSG0000....      PLXNB2     -1 HGNC:9104      intron_v....              G
    ##         biotype gene_symbol_source transcript_id   impact      flags
    ## 1  protein_....               HGNC  ENST0000.... MODIFIER
    ## 2  protein_....               HGNC  ENST0000.... MODIFIER cds_end_NF
    ## 3  protein_....               HGNC  ENST0000.... MODIFIER cds_end_NF
    ## 4  protein_....               HGNC  ENST0000.... MODIFIER
    ## 5  protein_....               HGNC  ENST0000.... MODIFIER
    ## 6  protein_....               HGNC  ENST0000.... MODIFIER
    ## 7  protein_....               HGNC  ENST0000.... MODIFIER
    ## 8  protein_....               HGNC  ENST0000.... MODIFIER
    ## 9  protein_....               HGNC  ENST0000.... MODIFIER
    ## 10 protein_....               HGNC  ENST0000.... MODIFIER
    ## 11 protein_....               HGNC  ENST0000.... MODIFIER
    ## 12 protein_....               HGNC  ENST0000.... MODIFIER
    ## 13 protein_....               HGNC  ENST0000.... MODIFIER
    ## 14 protein_....               HGNC  ENST0000.... MODIFIER
    ## 15 protein_....               HGNC  ENST0000.... MODIFIER
    ## 16 protein_....               HGNC  ENST0000.... MODIFIER
    ## 17 protein_....               HGNC  ENST0000.... MODIFIER
    ## 18 protein_....               HGNC  ENST0000.... MODIFIER
    ## 19 protein_....               HGNC  ENST0000.... MODIFIER
    ## 20 protein_....               HGNC  ENST0000.... MODIFIER
    ## 21 protein_....               HGNC  ENST0000.... MODIFIER
    ## 22 protein_....               HGNC  ENST0000.... MODIFIER
    ## 23 protein_....               HGNC  ENST0000.... MODIFIER
    ## 24 protein_....               HGNC  ENST0000.... MODIFIER
    ## 25 protein_....               HGNC  ENST0000.... MODIFIER
    ## 26 protein_....               HGNC  ENST0000.... MODIFIER

# Further work

An important element of prior work in ensemblVEP supports feeding annotation back into the VCF used to generate the effect prediction query. This seems feasible but concrete use cases are of interest.

# References

McLaren, William, Laurent Gil, Sarah E. Hunt, Harpreet Singh Riat, Graham R. S. Ritchie, Anja Thormann, Paul Flicek, and Fiona Cunningham. 2016. “The Ensembl Variant Effect Predictor.” Genome Biology 17 (1): 122. https://doi.org/10.1186/s13059-016-0974-4.