Bio Clinical Databases Clinvar Lookup

Version Compatibility

Reference examples tested with: requests 2.31+, cyvcf2 0.30+, pandas 2.2+, bcftools 1.19+, Entrez Direct 21.0+, lxml 5.0+ (for v2 XML schema).

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version then <tool> --help to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying. ClinVar XML schema v2 (rolled out in 2024) replaces <ClinVarSet> with <VariationArchive> as the top-level anchor; XSLT or parsers targeting the legacy element silently emit zero records.

ClinVar Lookup and Clinical-Significance Triangulation

'Look up the clinical significance of this variant' -> Retrieve ClinVar VCV-level aggregate, SCV-level submissions, ClinGen Variant Curation Expert Panel (VCEP) overrides, and conflict-resolution status.

• Python (REST): requests.get() against the E-utilities clinvar database
• Python (local VCF): cyvcf2.VCF('clinvar.vcf.gz') for batch queries against the weekly snapshot
• CLI: bcftools annotate -a clinvar.vcf.gz -c INFO/CLNSIG,INFO/CLNREVSTAT,INFO/CLNDN
• Cross-database: ClinGen Allele Registry CA ID via https://reg.clinicalgenome.org/

The Identifier Hierarchy (VCV / SCV / RCV): Get This Wrong and Everything Downstream Breaks

Operational footgun: the clinvar.vcf.gz CLNSIG field is the variant-level (VCV) aggregate. A variant Pathogenic for disease A but VUS for disease B collapses to "Pathogenic/Conflicting". For condition-stratified analysis, parse RCV-level XML, never CLNSIG alone.

2024 XML schema overhaul: ClinVar v2 XML separates GermlineClassification, SomaticClinicalImpact, and OncogenicityClassification under one <VariationArchive> anchor. The legacy <ClinicalSignificance> element is gone. Pipelines built before September 2024 against <ClinVarSet> silently emit zero records on new XML. The dual-release period ended December 2024.

Star Ratings and the Override Hierarchy

ClinVar does NOT retract or hide lower-star records when a VCEP publishes; a variant can simultaneously display "Pathogenic (3-star VCEP)" and "Conflicting interpretations (1-star)". Tools handle this differently (VarSeq, Franklin, GenoOx each pick a winner via different rules); this is a major source of inter-tool disagreement.

ClinGen Variant Curation Expert Panels (VCEPs)

As of 2025, ~80-90 VCEPs are approved or in progress across RASopathies, hereditary cancer (ENIGMA BRCA1/2, InSiGHT MMR), cardiomyopathy (sarcomere genes), hearing loss, RPE65/IRD, inborn errors of metabolism, and FH. The current count is moving; the authoritative directory is the Criteria Specification Registry at https://cspec.genome.network/cspec/ui/svi/all.

Each VCEP publishes a gene-disease-specific CSpec that re-weights ACMG/AMP criteria. The Hearing Loss VCEP downgrades PM2 to supporting by default and upgrades PS3 thresholds for OTOF. Treating "ACMG/AMP" as a single rubric across all genes is the most common error in non-specialist tooling.

ACMG/AMP, ClinGen SVI Specifications, and the Bayesian Point System

The Richards 2015 28-criterion framework is the foundation, but every modern automated classifier (InterVar, GeneBe, Franklin, VarSome) implements the Tavtigian 2018/2020 Bayesian point system, not the original combining rules. Strengths map to points: Supporting=1, Moderate=2, Strong=4, Very Strong=8 (benign codes negative). Final categories: P >=10, LP 6-9, VUS 0-5, LB -1 to -6, B <=-7.

For variant interpretation framework details, calibrated in-silico thresholds, and PVS1 decision-tree logic, defer to clinical-databases/acmg-classification. This skill focuses on querying ClinVar; it intentionally does not re-implement classification.

Conflicting Interpretations and Conflict Resolution

Harrison 2017 Genet Med 19:1096 (PMID 28301460) showed 87% of inter-lab conflicts were resolvable by reassessment plus data sharing. As of 2024, only 3.8% of conflicting BRCA1 missense VUS reached consensus despite years of effort; conflict resolution is slow even in best-curated genes.

Submission staleness is non-trivial: ClinVar does not push reclassifications to submitters; a 2017 SCV can persist on an active label in 2026 if the lab has not re-submitted. Genome Alert! (Yauy 2022 Genet Med) was built specifically to detect classification drift between weekly releases. The median delta is ~1,247 classification changes per month with potential clinical impact.

Decision Tree by Query Scenario

REST API Query (E-utilities)

Goal: Retrieve VCV-level ClinVar summary for a single variant by ID, gene, or HGVS.

Approach: Hit esummary.fcgi or esearch.fcgi against db=clinvar, parse JSON, then optionally hydrate to full record with efetch.

import requests

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

def clinvar_summary(variation_id):
    '''Retrieve VCV-level summary by ClinVar VariationID (do not confuse with CA ID).

    The germline / somatic / oncogenicity classification nesting shown below
    follows the ClinVar 2024 eSummary v2 schema described in the data-access
    documentation. Field names have changed between API versions -- inspect
    the actual JSON returned by eSummary for the live ClinVar version before
    pinning these key paths in production.
    '''
    r = requests.get(f'{EUTILS}/esummary.fcgi',
                     params={'db': 'clinvar', 'id': variation_id, 'retmode': 'json'},
                     timeout=30)
    r.raise_for_status()
    record = r.json()['result'][str(variation_id)]
    return {
        'vcv': record.get('accession'),
        'name': record.get('title'),
        'germline_class': record.get('germline_classification', {}).get('description'),
        'germline_review_status': record.get('germline_classification', {}).get('review_status'),
        'somatic_clinical': record.get('clinical_impact_classification', {}).get('description'),
        'oncogenicity': record.get('oncogenicity_classification', {}).get('description'),
        'last_evaluated': record.get('germline_classification', {}).get('last_evaluated')
    }

def clinvar_search_gene(gene, pathogenic_only=False, retmax=500):
    term = f'{gene}[gene]'
    if pathogenic_only:
        term += ' AND (clinsig_pathogenic[Properties] OR clinsig_likely_pathogenic[Properties])'
    r = requests.get(f'{EUTILS}/esearch.fcgi',
                     params={'db': 'clinvar', 'term': term, 'retmax': retmax, 'retmode': 'json'},
                     timeout=30)
    return r.json()['esearchresult']['idlist']

Local VCF Query (Weekly Snapshot)

Goal: Annotate or look up thousands of variants without rate limits.

Approach: Download the weekly clinvar.vcf.gz (note: only first-Thursday-of-month is archived; for longitudinal stability pin to monthly archives), query by genomic coordinates with cyvcf2 or annotate VCFs with bcftools.

mkdir -p clinvar/$(date +%Y%m); cd clinvar/$(date +%Y%m)
wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz
wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz.tbi

from cyvcf2 import VCF

clinvar = VCF('clinvar.vcf.gz')

def lookup(chrom, pos, ref, alt):
    '''Look up by GRCh38 coords. Returns variant-level (VCV) aggregate; not RCV.'''
    for v in clinvar(f'{chrom}:{pos}-{pos}'):
        if v.REF == ref and alt in v.ALT:
            info = v.INFO
            return {
                'vcv_id': info.get('ALLELEID'),
                'clnsig': info.get('CLNSIG'),
                'clnsig_conf': info.get('CLNSIGCONF'),
                'clnrevstat': info.get('CLNREVSTAT'),
                'clndn': info.get('CLNDN'),
                'clnvc': info.get('CLNVC'),
                'clnhgvs': info.get('CLNHGVS'),
                'clndisdb': info.get('CLNDISDB'),
                'oncdn': info.get('ONCDN'),
                'scidn': info.get('SCIDN')
            }
    return None

bcftools annotate \
    -a clinvar.vcf.gz \
    -c INFO/CLNSIG,INFO/CLNREVSTAT,INFO/CLNDN,INFO/CLNVC,INFO/CLNHGVS,INFO/CLNSIGCONF \
    input.vcf.gz -O z -o annotated.vcf.gz
bcftools index -t annotated.vcf.gz

ClinGen Allele Registry (CA IDs): The Real Cross-Database Anchor

ClinGen Allele Registry (https://reg.clinicalgenome.org/) computes a build-agnostic, transcript-agnostic CA ID (format CA######) for any allele projectable onto NCBI references (GRCh37, GRCh38, T2T-CHM13, any RefSeq transcript). The Registry covers ~700M+ alleles, vastly more than ClinVar. CA ID and ClinVar VariationID are one-to-one when a variant exists in ClinVar.

def car_id(hgvs_g):
    '''Resolve HGVS-g to canonical ClinGen Allele Registry CA ID.'''
    r = requests.put(f'https://reg.clinicalgenome.org/allele',
                     headers={'Content-Type': 'text/plain'},
                     data=hgvs_g, timeout=30)
    return r.json().get('@id', '').split('/')[-1] if r.ok else None

Use CA ID for any join touching non-ClinVar resources (gnomAD, dbSNP, COSMIC, MAVEdb). VariationID was renumbered during the 2017 ClinVar schema redesign; treating it as a stable cross-build identifier is unsafe.

Per-Operation Failure Modes

1. Treating CLNSIG as gospel for condition-specific work

• Trigger: Pull CLNSIG=Pathogenic from clinvar.vcf.gz and report variant as pathogenic for the patient's specific phenotype.
• Mechanism: CLNSIG is VCV-level aggregate; a variant can be P for disease A and B for disease B.
• Symptom: Patient phenotype does not match the disease where the variant is actually pathogenic; clinical action is wrong.
• Fix: Parse RCV-level XML (<RCVAccession> per condition); cross-check CLNDN and report per-condition classifications.

2. Parsing legacy XML against 2024 schema

• Trigger: XSLT or parser anchored on <ClinVarSet> or <ClinicalSignificance>.
• Mechanism: 2024 schema replaces both anchors with <VariationArchive> + germline/somatic/oncogenicity tripartite classifications.
• Symptom: Silent zero-record output, no error.
• Fix: Re-target to <VariationArchive> and read GermlineClassification, SomaticClinicalImpact, OncogenicityClassification separately.

3. Counting variant_summary.txt rows naively

• Trigger: wc -l variant_summary.txt to estimate variant count.
• Mechanism: One row per assembly per variant (GRCh37 and GRCh38); double-counts.
• Symptom: Counts inflated ~2x.
• Fix: awk -F'\t' '$17=="GRCh38"' variant_summary.txt | wc -l.

4. Trusting VariationID as a stable cross-build identifier

• Trigger: Join gnomAD-v4 records by ClinVar VariationID.
• Mechanism: VariationIDs were renumbered for a subset of variants during the 2017 schema overhaul.
• Symptom: Spurious mismatches at low rate (~1-2%).
• Fix: Use ClinGen Allele Registry CA ID, which is computed deterministically from sequence.

5. Ignoring star-rating override hierarchy

• Trigger: Pipeline picks the most-recent SCV regardless of review status.
• Mechanism: A 1-star SCV submitted yesterday outranks a 3-star VCEP curation from 2022 by date.
• Symptom: Clinical reports cite outdated or non-expert assertions over expert-panel decisions.
• Fix: Sort by review_status rank (4>3>2>1>0); use the highest-star record. For ties, sort by date.

6. Aggregating "Conflicting" without inspecting the conflict

• Trigger: Treat CLNSIG=Conflicting interpretations as VUS.
• Mechanism: "Conflicting" can mean (P vs LP), (P vs VUS), or (P vs LB); the clinical meaning is completely different across these.
• Symptom: Patients with high-evidence P variants reported as ambiguous; or true VUS reported as actionable.
• Fix: Parse CLNSIGCONF to see exact conflict; weight by submitter star.

7. Missing somatic interpretations

• Trigger: Pre-2024 pipeline reads only CLNSIG.
• Mechanism: Somatic classifications live in new INFO fields (ONCDN, SCIDN, CLNSIGSOMATIC) since 2024.
• Symptom: Cancer variants appear unclassified.
• Fix: Read ONCDN (oncogenicity disease name), SCIDN (somatic clinical impact disease name), and the somatic-specific significance fields.