omnilab/clinvar API reference

Omnilab\ClinVar

ClinVarSource class

final class ClinVarSource extends HttpSource ClinVarSource.php:37

ClinVar, the NCBI's archive of human variants and their clinical significance, through the E-utilities: a variation by its VariationID ("15333") or its VCV accession ("VCV000015333") - its name, type, germline classification, review status and date, the conditions it was classified for, its genes, protein change, molecular consequence, location, SPDI, allele frequencies, aliases, submissions -, its dbSNP id as a cross-reference, its genes (NCBI Gene) and its conditions (Mondo, OMIM, Orphanet, HPO) as related things; a search with ClinVar's query language ("rs334", "HBB[gene] AND pathogenic[clinsig]").

No key needed. NCBI asks every caller for its tool's name and an email address, and for three calls a second at most without an API key, ten with one: both are sent, and a 0.34 s (or 0.1 s) throttle kept; a 429 (the limit is per address, which other clients may share) is made again once after the wait NCBI asks. One call a variation (esummary), two a search page (esearch, esummary).

const BASE_URI = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/'

const MAX_LIMIT = 200

The most variations a search page holds (esummary takes them in one call).

ClinVarSource::__construct()

public function __construct(HttpClientInterface $http, readonly ?string $apiKey = null, readonly ?string $email = null, readonly string $tool = 'omnilab', string $baseUri = self::BASE_URI, array $headers = [], ?float $throttle = null, readonly int $retries = 1)

$email

sent with the tool's name, as NCBI asks: whom it writes to before it blocks a caller

$throttle

seconds between two calls; null: NCBI's, 0.34 without a key, 0.1 with one

$retries

how many times a call NCBI answers 429 is made again, after the wait it asks (10 s at most)

ClinVarSource::getName()

public function getName(): string

ClinVarSource::capabilities()

public function capabilities(): array

ClinVarSource::entity()

public function entity(Identifier|string $id): ?Entity

A variation by its VariationID ("15333", "clinvar:15333") or VCV accession ("VCV000015333", versioned or not, its page); a dbSNP id names a site, which may hold several variations (rs334: 15333, the sickle cell allele, and 15175): it is refused, as any other base's identifier, before any call - search() takes it; null when ClinVar has no such variation.

ClinVarSource::search()

public function search(Query $query): Page

The variations matching a text in ClinVar's query language (an rs id, a gene, a condition, fields as "HBB[gene] AND pathogenic[clinsig]"), in ClinVar's order; a domain other than biology answers nothing.

ClinVarSourceFactory class

final class ClinVarSourceFactory extends SourceFactory ClinVarSourceFactory.php:22

ClinVar, through the NCBI's E-utilities - no key needed, an API key for ten calls a second instead of three.

options: mailto: 'support@glitchr.io' # E-utilities' "email" and the User-Agent: whom NCBI writes to before it blocks a caller api_key: '...' # an NCBI API key (ncbi.nlm.nih.gov, account settings); never written here tool: 'omnilab' # E-utilities' "tool": the name NCBI knows the application by throttle: auto # seconds between two calls; auto: 0.34 without a key, 0.1 with one retries: 1 # a call NCBI answers 429 made again after the wait it asks (10 s at most) base_uri: 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/'

Options