1.2 Domain Background and Data Sources

Domain Background and Data Sources

Relevant source files

The following files were used as context for generating this wiki page:

• INTERVIEW.md
• LICENSE
• README.md
• docs/screenshots/TP53-desktop-light.png
• docs/screenshots/TP53-mobile.png

Purpose and Scope

This document outlines the biological data domain processed by VariantScope and details how external public databases are queried, parsed, and mapped into internal core modules. VariantScope integrates protein sequence metadata, 3D structural models, clinical variant interpretations, and population allele frequencies to evaluate the structural and population context of human gene variants README.md:1-5.

---

UniProt Accessions and Reference Sequences

The pipeline initiates with a gene symbol lookup (e.g., TP53, BRCA1) README.md:5. The UniProt data adapter translates this gene symbol into a stable UniProt accession and retrieves the canonical reference amino acid sequence README.md:67-68.

• Role: Establishes the authoritative coordinate system (residue numbering) used for all downstream sequence alignments, structural mapping, and variant validation INTERVIEW.md:28-30.
• Module: src/core/uniprot.js README.md:68

Title: "UniProt Reference Resolution"
flowchart TD
    A["GeneSymbol"] --> B["src/core/uniprot.js"]
    B --> C["UniProtAccession"]
    B --> D["CanonicalReferenceSequence"]

Sources: README.md:5-68, INTERVIEW.md:28-30

---

AlphaFold Structures and pLDDT Confidence Metrics

VariantScope maps 3D protein structures retrieved from the AlphaFold database README.md:5.

• pLDDT Extraction: AlphaFold stores per-residue confidence scores (pLDDT, Predicted Local Distance Difference Test) within the temperature factor (B-factor) column of the PDB file.
• Confidence Bins:
  • > 90: Very high confidence (dark blue ribbon) README.md:32
  • 70 to 90: Confident (light blue ribbon) README.md:32
  • 50 to 70: Low confidence (yellow ribbon) README.md:32
  • < 50: Very low confidence (orange ribbon) README.md:32
• Module: src/core/alphafold.js README.md:69

Title: "AlphaFold Structure and pLDDT Mapping"
flowchart TD
    A["AlphaFoldDatabase"] --> B["src/core/alphafold.js"]
    B --> C["PDBStructureCoordinates"]
    B --> D["BFactorColumnTo_pLDDT"]
    D --> E["ConfidenceColorBins"]

Sources: README.md:5-32, README.md:69

---

ClinVar Variant Classifications

Missense variants and their clinical interpretations are sourced from ClinVar README.md:71.

• Classifications: Categorizes amino acid substitutions by clinical significance, primarily Pathogenic, Likely Pathogenic, Benign, and Variant of Uncertain Significance (VUS) INTERVIEW.md:59.
• Mapping: Pathogenic variants are rendered as red spheres on the 3D structure; Benign (green) and VUS (gray) are optionally displayed README.md:32.
• Module: src/core/clinvar.js README.md:71

Title: "ClinVar Data Integration"
flowchart TD
    A["ClinVarAPI"] --> B["src/core/clinvar.js"]
    B --> C["MissenseVariants"]
    B --> D["ClinicalSignificance"]
    B --> E["ReviewStatus"]

Sources: README.md:32-71, INTERVIEW.md:59

---

gnomAD Allele Frequencies and Gene Constraint

Population genetics data is fetched from gnomAD to establish allele frequencies and gene-level selective constraint metrics README.md:5.

• Allele Frequencies: Used to compute lollipop stem heights via $-\log_{10}(\text{allele frequency})$, where variants absent in gnomAD receive maximum stem height README.md:33.
• Constraint Metrics: Evaluates gene tolerance to variation (e.g., LOEUF) to contextualize the evolutionary pressure on the protein.
• Module: src/core/gnomad.js README.md:72

Title: "gnomAD Frequency Pipeline"
flowchart TD
    A["gnomADAPI"] --> B["src/core/gnomad.js"]
    B --> C["AlleleFrequencies"]
    B --> D["GeneConstraintMetrics"]
    C --> E["RarityBucketsAndLollipops"]

Sources: README.md:5-33, README.md:72

---

Natural Language Space to Code Entity Space: Data Sources

The following diagram connects high-level domain concepts and external biological databases to their corresponding implementation files and core parsing functions within the codebase.

Title: "Domain Concept to Code Entity Mapping"
flowchart TB
    subgraph NaturalLanguageSpace ["Natural Language Space"]
        A["Gene Symbol Search"]
        B["AlphaFold 3D & pLDDT"]
        C["ClinVar Pathogenicity"]
        D["gnomAD Frequencies"]
    end

    subgraph CodeEntitySpace ["Code Entity Space"]
        E["src/core/uniprot.js"]
        F["src/core/alphafold.js"]
        G["src/core/clinvar.js"]
        H["src/core/gnomad.js"]
        I["src/core/parse.js"]
    end

    A --> E
    B --> F
    C --> G
    D --> H
    E --> I
    F --> I
    G --> I
    H --> I

Sources: README.md:67-72

---

Joining and Numbering Validation Pipeline

Joining ClinVar records with gnomAD population frequencies presents significant ambiguity due to differing database nomenclature and transcript versions INTERVIEW.md:18-29.

• Coordinate-First Matching: Exact genomic coordinates and base changes are prioritized for matching ClinVar variants to gnomAD entries INTERVIEW.md:18-21. Protein-change shortcuts (e.g., R175H) are avoided unless coordinates are missing and exactly one gnomAD variant uniquely maps, preventing silent frequency assignment errors INTERVIEW.md:18-21.
• Numbering Validation: Residue numbers are validated against the reference UniProt sequence (src/core/uniprot.js). If an amino acid mismatch occurs at position $N$, the variant is excluded from structural rendering INTERVIEW.md:28-30.

Title: "Joining and Validation Logic"
flowchart TD
    A["ClinVarRecord"] --> C["src/core/join.js"]
    B["gnomADRecord"] --> C
    C --> D["CoordinateMatchCheck"]
    D -- "Exact match" --> F["ValidatedVariant"]
    D -- "Ambiguous/Missing" --> E["ProteinChangeFallback"]
    E -- "Unique match" --> F
    E -- "Multi-match" --> G["MarkUnknown"]
    F --> H["src/core/parse.js"]
    H --> I["ResidueNumberingValidation"]

Sources: INTERVIEW.md:18-30, README.md:86

---