Query NCBI ClinVar for variant clinical significance. Search by gene/position, interpret pathogenicity classifications, access via E-utilities API or FTP, annotate VCFs, for genomic medicine.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Query NCBI ClinVar for variant clinical significance. Search by gene/position, interpret pathogenicity classifications, access via E-utilities API or FTP, annotate VCFs, for genomic medicine.
ClinVar Database
Overview
ClinVar is NCBI's freely accessible archive of reports on relationships between human genetic variants and phenotypes, with supporting evidence. The database aggregates information about genomic variation and its relationship to human health, providing standardized variant classifications used in clinical genetics and research.
When to Use This Skill
This skill should be used when:
Searching for variants by gene, condition, or clinical significance
By variant: NM_000059.3:c.1310_1313del[variant name]
By chromosome: 13[chr]
Combined: BRCA1[gene] AND pathogenic[CLNSIG]
Programmatic Access via E-utilities
Access ClinVar programmatically using NCBI's E-utilities API. Refer to for comprehensive API documentation including:
references/api_reference.md
esearch - Search for variants matching criteria
esummary - Retrieve variant summaries
efetch - Download full XML records
elink - Find related records in other NCBI databases
Quick example using curl:
# Search for pathogenic BRCA1 variants
curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term=BRCA1[gene]+AND+pathogenic[CLNSIG]&retmode=json"
Best practices:
Test queries on the web interface before automating
Use API keys to increase rate limits from 3 to 10 requests/second
Implement exponential backoff for rate limit errors
Set Entrez.email when using Biopython
2. Interpret Clinical Significance
Understanding Classifications
ClinVar uses standardized terminology for variant classifications. Refer to references/clinical_significance.md for detailed interpretation guidelines.
# Download latest monthly XML release
wget ftp://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/clinvar_variation/ClinVarVariationRelease_00-latest.xml.gz
# Download VCF for GRCh38
wget ftp://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz
4. Process and Analyze ClinVar Data
Working with XML Files
Process XML files to extract variant details, classifications, and evidence.
Python example with xml.etree:
import gzip
import xml.etree.ElementTree as ET
with gzip.open('ClinVarVariationRelease.xml.gz', 'rt') as f:
for event, elem in ET.iterparse(f, events=('end',)):
if elem.tag == 'VariationArchive':
variation_id = elem.attrib.get('VariationID')
# Extract clinical significance, review status, etc.
elem.clear() # Free memory
Working with VCF Files
Annotate variant calls or filter by clinical significance using bcftools or Python.
Using bcftools:
# Filter pathogenic variants
bcftools view -i 'INFO/CLNSIG~"Pathogenic"' clinvar.vcf.gz
# Extract specific genes
bcftools view -i 'INFO/GENEINFO~"BRCA"' clinvar.vcf.gz
# Annotate your VCF with ClinVar
bcftools annotate -a clinvar.vcf.gz -c INFO your_variants.vcf
Using PyVCF in Python:
import vcf
vcf_reader = vcf.Reader(filename='clinvar.vcf.gz')
for record in vcf_reader:
clnsig = record.INFO.get('CLNSIG', [])
if'Pathogenic'in clnsig:
gene = record.INFO.get('GENEINFO', [''])[0]
print(f"{record.CHROM}:{record.POS}{gene} - {clnsig}")
Working with Tab-Delimited Files
Use pandas or command-line tools for rapid filtering and analysis.
Using pandas:
import pandas as pd
# Load variant summary
df = pd.read_csv('variant_summary.txt.gz', sep='\t', compression='gzip')
# Filter pathogenic variants in specific gene
pathogenic_brca = df[
(df['GeneSymbol'] == 'BRCA1') &
(df['ClinicalSignificance'].str.contains('Pathogenic', na=False))
]
# Count variants by clinical significance
sig_counts = df['ClinicalSignificance'].value_counts()
Using command-line tools:
# Extract pathogenic variants for specific gene
zcat variant_summary.txt.gz | \
awk -F'\t''$7=="TP53" && $13~"Pathogenic"' | \
cut -f1,5,7,13,14
5. Handle Conflicting Interpretations
When multiple submitters provide different classifications for the same variant, ClinVar reports "Conflicting interpretations of pathogenicity."
Resolution strategy:
Check review status (star rating) - higher ratings carry more weight
Examine evidence and assertion criteria from each submitter
Consider submission dates - newer submissions may reflect updated evidence
Review population frequency data (e.g., gnomAD) for context
Consult expert panel classifications (★★★) when available
For clinical use, always defer to a genetics professional
Search query to exclude conflicts:
TP53[gene] AND pathogenic[CLNSIG] NOT conflicting[RVSTAT]
6. Track Classification Updates
Variant classifications may change over time as new evidence emerges.
Why classifications change:
New functional studies or clinical data
Updated population frequency information
Revised ACMG/AMP guidelines
Segregation data from additional families
Best practices:
Document ClinVar version and access date for reproducibility
Re-check classifications periodically for critical variants
Subscribe to ClinVar mailing list for major updates
Use monthly archived releases for stable datasets
7. Submit Data to ClinVar
Organizations can submit variant interpretations to ClinVar.
Historical submissions may be outdated - Newer data may be more accurate
VUS classification is not a clinical diagnosis - Means insufficient evidence
Scope Limitations
Not for direct clinical diagnosis - Always involve genetics professional
Population-specific - Variant frequencies vary by ancestry
Incomplete coverage - Not all genes or variants are well-studied
Version dependencies - Coordinate genome build (GRCh37/GRCh38) across analyses
Technical Limitations
VCF files exclude large variants - Variants >10kb not in VCF format
Rate limits on API - 3 req/sec without key, 10 req/sec with API key
File sizes - Full XML releases are multi-GB compressed files
No real-time updates - Website updated weekly, FTP monthly/weekly
Resources
Reference Documentation
This skill includes comprehensive reference documentation:
references/api_reference.md - Complete E-utilities API documentation with examples for esearch, esummary, efetch, and elink; includes rate limits, authentication, and Python/Biopython code samples
references/clinical_significance.md - Detailed guide to interpreting clinical significance classifications, review status star ratings, conflict resolution, and best practices for variant interpretation
references/data_formats.md - Documentation for XML, VCF, and tab-delimited file formats; FTP directory structure, processing examples, and format selection guidance
