Consequence predictions for any number of variants

vep_variants() refuses more than the 200 VEP accepts per POST. This chunks the input at chunk_size and dispatches the chunks through biohttp::post_json_many(), so a variant table of any length is a handful of requests rather than a loop written at every call site.

Usage

vep_variants_all(
  chrom,
  pos,
  ref,
  alt,
  chunk_size = VEP_BATCH,
  options = vep_default_options(),
  throttle = vep_default_throttle(),
  ...
)

Arguments

chrom, pos, ref, alt

Variant components, all the same length.

chunk_size

Variants per request, at most VEP_BATCH (200).

options

A named list of VEP request flags. See vep_default_options() for the supported flags and what each one adds to the result.

throttle

A throttle spec passed to biohttp::post_json_many(). Defaults to vep_default_throttle(); pass NULL to disable pacing.

...

Passed to biohttp::post_json_many(), for example max_active.

Value

A biohttp envelope whose data is a tibble with one row per variant, in the order asked: the columns of vep_parse_batch() plus status, which is "ok" for a row whose chunk was answered and the failing envelope's status otherwise.

A failed chunk is rows of NA, not a failed call

Following gnomad_constraints(). Each chunk's envelope is inspected on its own; a chunk that failed yields a row of NA per variant carrying the envelope status in status, while the chunks that succeeded are parsed as usual. Partial failure is the normal case across many requests, and taking the whole call down would throw away the answers that did arrive. Only when every chunk failed is the first failing envelope returned, so an outage still reads as one.

Sorted and deduplicated before chunking

The input is put in genome order and a repeated variant is sent once, not once per occurrence, before it is split into chunks. Neither changes the contract: the return is still one row per input, in input order, and a repeated variant's positions all carry the same answer (which they did not necessarily do before, when duplicates could land in different chunks and see different transient failures). What it does change is how many requests go out: a coding lane's ~1500 multiallelic-split duplicates stop costing a request each, and a stable chunk order gives biohttp's per-chunk cache a real chance to hit between two calls that share a background.

References

McLaren et al. (2016). The Ensembl Variant Effect Predictor. Genome Biology 17, 122. doi:10.1186/s13059-016-0974-4

Service documentation: https://rest.ensembl.org/

Examples

# \donttest{
biohttp::body_or_null(vep_variants_all(
  c("7", "17"),
  c(140753336, 7676154),
  c("A", "G"),
  c("T", "C")
))
#> # A tibble: 2 × 35
#>   key            gene  consequence mane  impact exon  protein_pos sift  polyphen
#>   <chr>          <chr> <chr>       <chr> <chr>  <chr>       <int> <chr> <chr>   
#> 1 7-140753336-A… BRAF  missense_v… NM_0… MODER… 15/18         600 dele… probabl…
#> 2 17-7676154-G-C TP53  missense_v… NM_0… MODER… 4/11           72 tole… benign  
#> # ℹ 26 more variables: alphamissense <dbl>, alphamissense_class <chr>,
#> #   transcript <chr>, gene_id <chr>, biotype <chr>, hgvsc <chr>, hgvsp <chr>,
#> #   canonical <lgl>, codons <chr>, amino_acids <chr>, cadd_phred <dbl>,
#> #   cadd_raw <dbl>, revel <dbl>, spliceai_ds_ag <dbl>, spliceai_ds_al <dbl>,
#> #   spliceai_ds_dg <dbl>, spliceai_ds_dl <dbl>, spliceai_max <dbl>, lof <chr>,
#> #   rsid <chr>, gnomadg_af <dbl>, gnomade_af <dbl>, gnomadg_af_max <dbl>,
#> #   gnomade_af_max <dbl>, clin_sig <chr>, status <chr>
# }