Repository navigation
2.1 Data Source Adapters
Relevant source files
The following files were used as context for generating this wiki page:
The data source adapters are responsible for querying external bioinformatics web services, handling network request coordination, rate limiting, and transforming raw API payloads into structured core data models used throughout VariantScope. The core adapter modules reside in src/core and interact with UniProt, AlphaFold DB, NCBI ClinVar, and gnomAD.
Sources: src/core/uniprot.js:1-56, src/core/alphafold.js:1-60, src/core/clinvar.js:1-174, src/core/gnomad.js:1-82, src/core/parse.js:1-117
The UniProt adapter translates a user-supplied gene symbol into a primary protein accession, protein name, length, and the canonical amino acid sequence src/core/uniprot.js:1-2. All downstream coordinate mappings rely on this canonical sequence.
UniProt searches use the REST API search endpoint src/core/uniprot.js:4. Gene symbols are first validated using isValidGeneSymbol src/core/uniprot.js:17-19, which enforces a strict alphanumeric pattern (/^[A-Za-z0-9-]{1,20}$/) to prevent query malformation.
Queries enforce exact gene matching (gene_exact), restricted to human taxonomy (organism_id:9606) and reviewed Swiss-Prot entries (reviewed:true) src/core/uniprot.js:24:
const query = `gene_exact:${symbol} AND organism_id:9606 AND reviewed:true`;If multiple hits are returned, fetchUniprot prefers the hit whose official gene name matches the requested symbol, throwing a GeneNotFoundError if zero hits match src/core/uniprot.js:37-41.
Sources: src/core/uniprot.js:1-56
The AlphaFold adapter fetches predicted 3D structures (PDB format text) and per-residue confidence scores (pLDDT) for a given UniProt accession src/core/alphafold.js:1-2.
AlphaFold predictions are queried from the EBI API endpoint src/core/alphafold.js:4. The function fetchAlphaFold resolves the canonical model identifier (AF-<accession>-F1) and downloads the corresponding PDB text URL src/core/alphafold.js:35-45.
Residue confidence (pLDDT) is parsed directly from the B-factor column of C-alpha atoms in the PDB file via parsePlddt src/core/alphafold.js:6-20:
export function parsePlddt(pdbText) {
const values = [];
for (const line of pdbText.split('\n')) {
if (!line.startsWith('ATOM') || line.slice(12, 16).trim() !== 'CA') continue;
const residueNumber = Number(line.slice(22, 26));
const bFactor = Number(line.slice(60, 66));
if (Number.isInteger(residueNumber) && residueNumber >= 1 && Number.isFinite(bFactor)) {
values[residueNumber - 1] = bFactor;
}
}
return Array.from(values, (value) => value ?? null);
}Sources: src/core/alphafold.js:1-60
The ClinVar adapter queries NCBI E-utilities (esearch.fcgi and esummary.fcgi) to retrieve missense variants, germline classifications, review statuses, and SPDI genomic coordinates for a specified gene src/core/clinvar.js:1-115.
NCBI allows up to 3 requests per second without an API key. To comply with this limit, clinvar.js maintains a promise queue (queue) and a minimum network gap (NCBI_GAP_MS = 400) via ncbiGet src/core/clinvar.js:59-77.
Records returned by esummary are processed by parseSummaryRecord src/core/clinvar.js:118-144. This function validates that the record belongs to the target gene, extracts protein change strings, and normalizes germline classifications into standard categories (Pathogenic, Benign, VUS, etc.).
Sources: src/core/clinvar.js:1-174
The gnomAD adapter queries the Broad Institute gnomAD GraphQL API (API_URL) to fetch population allele frequencies for missense variants and gene-level constraint metrics (pli, loeuf, misZ) src/core/gnomad.js:1-82.
fetchGnomadVariants and fetchGnomadConstraint dispatch POST requests containing GraphQL query strings targeting gnomad_r4 on GRCh38 src/core/gnomad.js:6-34. If the GraphQL response includes an errors array, graphql() throws a custom GnomadError src/core/gnomad.js:9-28.
Sources: src/core/gnomad.js:1-82
The parsing module provides robust string manipulation routines shared across data adapters to normalize biological nomenclature src/core/parse.js:1-117:
-
parseProteinChange(text): Parses protein changes (p.Arg1699TrporR1699W) into structured objects{ok, refAA, position, altAA}, filtering out non-missense variants (frameshifts, delins, synonymous changes) src/core/parse.js:52-77. -
normalizeClassification(description): Maps arbitrary ClinVar clinical significance text to canonical labels (Pathogenic,Likely pathogenic,VUS,Conflicting,Benign,Likely benign) src/core/parse.js:88-102. -
spdiToVariantId(spdi): Converts ClinVar SPDI strings into gnomAD-compatible variant IDs (17-43067638-C-T) src/core/parse.js:106-111.
Sources: src/core/parse.js:1-117
graph TD
UserQuery["User Gene Symbol input"] -->|isValidGeneSymbol| UniProtCode["fetchUniprot() in src/core/uniprot.js"]
UniProtCode -->|Primary Accession & Length| AlphaFoldCode["fetchAlphaFold() in src/core/alphafold.js"]
UniProtCode -->|Gene Symbol| ClinVarCode["esearch / esummary in src/core/clinvar.js"]
UniProtCode -->|Gene Symbol| GnomadCode["fetchGnomadVariants() in src/core/gnomad.js"]
AlphaFoldCode -->|pdbText & pLDDT Array| ParseAlphaFold["parsePlddt() in src/core/alphafold.js"]
ClinVarCode -->|Raw Summaries| ParseClinVar["parseSummaryRecord() in src/core/clinvar.js"]
GnomadCode -->|GraphQL Data| ParseGnomad["parseProteinChange() in src/core/parse.js"]
ParseClinVar --> Normalize["normalizeClassification() in src/core/parse.js"]
ParseGnomad --> VariantKey["proteinKey() in src/core/parse.js"]
Sources: src/core/uniprot.js:1-56, src/core/alphafold.js:1-60, src/core/clinvar.js:1-174, src/core/gnomad.js:1-82, src/core/parse.js:1-117
graph TD
Start["Call ncbiGet(url, req)"] --> QueueCheck["Await queue promise"]
QueueCheck --> GapCheck{"Time since lastNetworkCall < NCBI_GAP_MS?"}
GapCheck -->|Yes| Sleep["sleep(remainingMs, signal)"]
GapCheck -->|No| Fetch["getJson(url) via src/core/http.js"]
Sleep --> Fetch
Fetch --> UpdateTimestamp["Update lastNetworkCall = Date.now()"]
UpdateTimestamp --> Resolve["Resolve network reply"]
Sources: src/core/clinvar.js:57-77
Content imported from DeepWiki.