Searches ClinVar for term and returns the classification of one record.
Arguments
- term
A search term. An SPDI or a VCV accession matches one record; an rsID or an HGVS name can match several.
- throttle
A throttle spec, see
biohttp::req_defaults(). Defaults to the documented E-utilities rate for the key in use.- allele
Optional. The protein change you mean, such as
"V600E"or"p.Val600Glu", for atermthat can match several records.NULL,NAand""mean no filter.- ...
Passed to
biohttp::get_json().
Value
A biohttp envelope whose data is a one-row tibble with the columns
of clinvar_parse_record() and n_matches, the number of records that fit
the request. no_data when nothing matches, including when no record has
the protein change in allele.
A term can match several records
ClinVar's search is a text search, and an rsID or an HGVS name often matches
more than one record. rs113488022 matches BRAF V600G and V600E, and ClinVar
lists V600G first. NM_004333.6:c.1799T>A, the HGVS name of V600E, lists
BRAF I208V first, a different variant at a different position.
There are two ways to get the record you mean:
Pass a precise
term. An SPDI such asNC_000007.14:140753335:A:T, or a VCV accession such asVCV000013961, matches one record.Pass
allele, the protein change you mean, such as"V600E"or"p.Val600Glu". It is checked against each record's own list of protein changes, and the first record that has it is returned.
Without either, the first record ClinVar lists is returned, and n_matches
says how many records the term matched. A value above 1 means the row may be
for a different variant from the one you meant.
Only the first 20 records ClinVar lists are fetched, so allele is checked
against those. An rsID or an HGVS name matches far fewer.
The NCBI API key
Set NCBI_API_KEY and both requests carry it, which raises the rate limit
from 3 to 10 requests a second. It is passed as a secret_query, so it stays
out of the cache key and out of every message. Without one the client works
at the lower limit, and the default throttle follows: 3 a second without
a key, 10 with one.
Identifying the caller
NCBI asks every client to send tool and email. They are read from
BIOHTTP_CALLER_IDENTITY and BIOHTTP_CONTACT_EMAIL, the same variables
biohttp builds its User-Agent from, and a blank one is omitted. They are
ordinary query parameters, so they are part of the cache key.
References
Landrum et al. (2018). ClinVar: improving access to variant interpretations and supporting evidence. Nucleic Acids Research 46(D1), D1062-D1067. doi:10.1093/nar/gkx1153
Service documentation: https://www.ncbi.nlm.nih.gov/clinvar/
Examples
# \donttest{
biohttp::body_or_null(clinvar_classification("NC_000007.14:140753335:A:T"))
#> # A tibble: 1 × 8
#> uid accession title significance review_status last_evaluated conditions
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 13961 VCV000013961 NM_00… Conflicting… criteria pro… 2026/03/11 00… BRAF-rela…
#> # ℹ 1 more variable: n_matches <int>
biohttp::body_or_null(clinvar_classification("rs113488022", allele = "V600E"))
#> Waiting 2s for retry backoff ■■■■■■■■■■■■■■■
#> Waiting 2s for retry backoff ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
#> # A tibble: 1 × 8
#> uid accession title significance review_status last_evaluated conditions
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 13961 VCV000013961 NM_00… Conflicting… criteria pro… 2026/03/11 00… BRAF-rela…
#> # ℹ 1 more variable: n_matches <int>
# }