bio-clinical-databases-clinvar-lookup

name	bio-clinical-databases-clinvar-lookup
description	Query ClinVar for variant pathogenicity classifications, review status, and disease associations via REST API or local VCF. Use when determining clinical significance of variants for diagnostic or research purposes.
tool_type	python
primary_tool	requests

Version Compatibility

Reference examples tested with: Entrez Direct 21.0+, bcftools 1.19+

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 Lookup

REST API Queries

Goal: Retrieve ClinVar pathogenicity classifications and disease associations for variants via REST API.

Approach: Query NCBI E-utilities endpoints with variant IDs, gene symbols, or HGVS notation and parse JSON responses.

"Look up this variant in ClinVar" → Query ClinVar database for clinical significance, review status, and disease associations.

• Python: requests.get() against NCBI E-utilities (requests)
• CLI: esearch/efetch (Entrez Direct)

Query by Variant ID

import requests

def query_clinvar_by_id(variation_id):
    '''Query ClinVar by variation ID'''
    url = f'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi'
    params = {
        'db': 'clinvar',
        'id': variation_id,
        'retmode': 'json'
    }
    response = requests.get(url, params=params)
    return response.json()

result = query_clinvar_by_id('16609')

Search by Gene

def search_clinvar_gene(gene_symbol, pathogenic_only=False):
    '''Search ClinVar for variants in a gene'''
    url = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi'

    term = f'{gene_symbol}[gene]'
    if pathogenic_only:
        term += ' AND pathogenic[clinical_significance]'

    params = {
        'db': 'clinvar',
        'term': term,
        'retmax': 500,
        'retmode': 'json'
    }
    response = requests.get(url, params=params)
    return response.json()

Search by HGVS

def search_clinvar_hgvs(hgvs):
    '''Search ClinVar by HGVS notation'''
    url = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi'
    params = {
        'db': 'clinvar',
        'term': f'{hgvs}[variant name]',
        'retmode': 'json'
    }
    response = requests.get(url, params=params)
    return response.json()

Local ClinVar VCF

Goal: Query variants against a local ClinVar VCF for fast, offline pathogenicity lookups.

Approach: Download the ClinVar VCF from NCBI FTP, then query by genomic coordinates using cyvcf2 or bcftools.

Download ClinVar VCF

# GRCh38
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

# GRCh37
wget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh37/clinvar.vcf.gz

Query Local ClinVar with cyvcf2

from cyvcf2 import VCF

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

def lookup_variant(chrom, pos, ref, alt):
    '''Look up variant in local ClinVar VCF'''
    region = f'{chrom}:{pos}-{pos}'
    for variant in clinvar(region):
        if variant.REF == ref and alt in variant.ALT:
            return {
                'clnsig': variant.INFO.get('CLNSIG'),
                'clnrevstat': variant.INFO.get('CLNREVSTAT'),
                'clndn': variant.INFO.get('CLNDN'),
                'clnvc': variant.INFO.get('CLNVC')
            }
    return None

result = lookup_variant('7', 140453136, 'A', 'T')

Clinical Significance Categories

Value	Interpretation
Pathogenic	Disease-causing
Likely_pathogenic	Probably disease-causing
Uncertain_significance	VUS - unknown
Likely_benign	Probably not disease-causing
Benign	Not disease-causing
Conflicting_interpretations	Multiple labs disagree

Review Status Stars

Stars	Review Status
4	Practice guideline
3	Expert panel reviewed
2	Multiple submitters, criteria provided
1	Single submitter, criteria provided
0	No assertion criteria

Parse ClinVar INFO Fields

Goal: Classify variants into actionable pathogenicity categories from raw ClinVar CLNSIG values.

Approach: Map ClinVar significance terms to simplified categories (pathogenic, benign, conflicting, VUS).

def parse_clinvar_significance(clnsig):
    '''Parse ClinVar CLNSIG field'''
    pathogenic_terms = ['Pathogenic', 'Likely_pathogenic']
    benign_terms = ['Benign', 'Likely_benign']

    if any(term in clnsig for term in pathogenic_terms):
        return 'pathogenic'
    elif any(term in clnsig for term in benign_terms):
        return 'benign'
    elif 'Conflicting' in clnsig:
        return 'conflicting'
    else:
        return 'vus'

Batch Annotation with bcftools

Goal: Annotate an entire VCF with ClinVar significance, review status, and disease names in one pass.

Approach: Use bcftools annotate to transfer ClinVar INFO fields from the ClinVar VCF to the input VCF.

# Annotate VCF with ClinVar
bcftools annotate \
    -a clinvar.vcf.gz \
    -c INFO/CLNSIG,INFO/CLNREVSTAT,INFO/CLNDN \
    input.vcf.gz \
    -o annotated.vcf.gz

Related Skills

• myvariant-queries - Aggregated queries including ClinVar
• variant-prioritization - Filter by ClinVar significance
• variant-calling/clinical-interpretation - ACMG guidelines