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.
\nThis skill should be used when:
\n| Scenario | \nUse Instead | \n
|---|---|
| Population allele frequency / ancestry-specific AF, gnomAD constraint | \nalterlab-gnomad | \n
| Somatic cancer mutation catalog, Cancer Gene Census, mutational signatures | \nalterlab-cosmic | \n
| How often a gene is mutated in tumor cohorts (TCGA, MSK-IMPACT) | \nalterlab-cbioportal | \n
| Pharmacogenomic gene–drug dosing (CPIC/DPWG) | \nalterlab-clinpgx | \n
Three classification types (since 2024). ClinVar now keeps separate aggregate\nclassifications for germline pathogenicity (ACMG/AMP), somatic clinical impact\n(AMP/ASCO/CAP tiers), and oncogenicity (ClinGen/CGC/VICC). APIs and files expose them\nseparately: esummary JSON has germline_classification, clinical_impact_classification,\nand oncogenicity_classification objects (each with description and review_status;\nthere is no longer a clinical_significance field); the VCF has CLNSIG/CLNREVSTAT\n(germline), ONC/ONCREVSTAT, and SCI/SCIREVSTAT; variant_summary.txt has\nClinicalSignificance (germline) plus SomaticClinicalImpact and Oncogenicity columns.
Search ClinVar using the web interface at https://www.ncbi.nlm.nih.gov/clinvar/
\nCommon search patterns (field tags verified against the live einfo field list — there is no [CLNSIG] or [RVSTAT] field; using them silently falls back to [All Fields] and does NOT filter):
BRCA1[gene]clinsig_pathogenic[Properties] (also clinsig_likely_pathogenic, clinsig_benign, clinsig_likely_benign, clinsig_vus, clinsig_has_conflicts — note VUS is clinsig_vus; clinsig_uncertain matches nothing)\"reviewed by expert panel\"[Review status], \"practice guideline\"[Review status], \"criteria provided, single submitter\"[Review status]\"breast cancer\"[Disease/Phenotype]\"c.1310_1313del\"[Variant name]13[chr]BRCA1[gene] AND clinsig_pathogenic[Properties]Access ClinVar programmatically using NCBI's E-utilities API. Refer to references/api_reference.md for comprehensive API documentation including:
Quick example using curl:
\n# Search for pathogenic BRCA1 variants\ncurl \"https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term=BRCA1[gene]+AND+clinsig_pathogenic[Properties]&retmode=json\"\nAlways inspect the querytranslation field in the response: if a [...] tag is unknown, NCBI rewrites it to [All Fields] and your filter is silently dropped.
Best practices:
\nEntrez.email when using BiopythonClinVar uses standardized terminology for variant classifications. Refer to references/clinical_significance.md for detailed interpretation guidelines.
Key germline classification terms (ACMG/AMP):
\nReview status (star ratings):
\nCritical considerations:
\nDownload complete datasets from https://ftp.ncbi.nlm.nih.gov/pub/clinvar/ (same tree over HTTPS or FTP)
Refer to references/data_formats.md for comprehensive documentation on file formats and processing.
Update schedule:
\nXML files (most comprehensive; current format since 2025-08-07, with separate germline / somatic elements):
\nxml/ClinVarVCVRelease_YYYY-MM.xml.gz (+ _00-latest symlink) - Variant-centric aggregationxml/RCV_release/ClinVarRCVRelease_YYYY-MM.xml.gz - Variant-condition pairsClinVarVariationRelease / ClinVarFullRelease formats (single classification element) are frozen in xml/VCV_xml_old_format/ and xml/RCV_xml_old_format/ and no longer supportedVCF files (for genomic pipelines):
\nvcf_GRCh37/clinvar.vcf.gzvcf_GRCh38/clinvar.vcf.gzTab-delimited files (for quick analysis):
\ntab_delimited/variant_summary.txt.gz - Summary of all variantstab_delimited/var_citations.txt.gz - PubMed citationstab_delimited/cross_references.txt.gz - Database cross-referencesExample download:
\n# Download latest monthly VCV XML release\nwget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/ClinVarVCVRelease_00-latest.xml.gz\n\n# Download VCF for GRCh38\nwget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz\nProcess XML files to extract variant details, classifications, and evidence.
\nPython example with xml.etree:
\nimport gzip\nimport xml.etree.ElementTree as ET\n\nwith gzip.open('ClinVarVCVRelease_00-latest.xml.gz', 'rt') as f:\n for event, elem in ET.iterparse(f, events=('end',)):\n if elem.tag == 'VariationArchive':\n variation_id = elem.attrib.get('VariationID')\n # Aggregate germline call lives under ClassifiedRecord/Classifications\n germline = elem.find('ClassifiedRecord/Classifications/GermlineClassification')\n if germline is not None:\n classification = germline.findtext('Description') # e.g. \"Pathogenic/Likely pathogenic\"\n review_status = germline.findtext('ReviewStatus')\n elem.clear() # Free memory\nAnnotate variant calls or filter by clinical significance using bcftools or Python.
\nUsing bcftools:
\n# Filter pathogenic variants\nbcftools view -i 'INFO/CLNSIG~\"Pathogenic\"' clinvar.vcf.gz\n\n# Extract specific genes\nbcftools view -i 'INFO/GENEINFO~\"BRCA\"' clinvar.vcf.gz\n\n# Annotate your VCF with ClinVar\nbcftools annotate -a clinvar.vcf.gz -c INFO your_variants.vcf\nUsing pysam in Python (the old PyVCF/import vcf package is unmaintained and breaks on Python 3.10+; use pysam or cyvcf2 instead):
import pysam\n\nvcf = pysam.VariantFile(\"clinvar.vcf.gz\")\nfor rec in vcf:\n # CLNSIG is a comma/pipe-delimited string (e.g. \"Pathogenic/Likely_pathogenic\");\n # match as substring, not equality.\n clnsig = str(rec.info.get(\"CLNSIG\", \"\"))\n if \"Pathogenic\" in clnsig:\n gene = rec.info.get(\"GENEINFO\", \"\")\n print(f\"{rec.chrom}:{rec.pos} {gene} - {clnsig}\")\nUse pandas or command-line tools for rapid filtering and analysis.
\nUsing pandas:
\nimport pandas as pd\n\n# Load variant summary (one row per variant *per assembly* — keep one build,\n# or every count is doubled)\ndf = pd.read_csv('variant_summary.txt.gz', sep='\\t', compression='gzip', low_memory=False)\ndf = df[df['Assembly'] == 'GRCh38']\n\n# Filter pathogenic variants in specific gene\npathogenic_brca = df[\n (df['GeneSymbol'] == 'BRCA1') &\n (df['ClinicalSignificance'].str.contains('Pathogenic', na=False))\n]\n\n# Count variants by clinical significance\nsig_counts = df['ClinicalSignificance'].value_counts()\nUsing command-line tools:
\n# Extract pathogenic TP53 variants (GRCh38 rows). Columns: 3 Name, 5 GeneSymbol,\n# 7 ClinicalSignificance (germline), 17 Assembly, 25 ReviewStatus, 31 VariationID\nzcat variant_summary.txt.gz | \\\n awk -F'\\t' '$5==\"TP53\" && $7~/Pathogenic/ && $17==\"GRCh38\"' | \\\n cut -f3,5,7,25,31\nWhen multiple submitters provide different classifications for the same variant, ClinVar reports \"Conflicting classifications of pathogenicity\" (renamed from \"Conflicting interpretations\" in 2024; VCF value Conflicting_classifications_of_pathogenicity, review status \"criteria provided, conflicting classifications\").
Resolution strategy:
\nSearch query to exclude conflicts:
\nTP53[gene] AND clinsig_pathogenic[Properties] NOT clinsig_has_conflicts[Properties]\nVariant classifications may change over time as new evidence emerges.
\nWhy classifications change:
\nBest practices:
\nOrganizations can submit variant interpretations to ClinVar.
\nSubmission methods:
\nreferences/api_reference.mdRequirements:
\nContact: clinvar@ncbi.nlm.nih.gov for submission account setup.
\nObjective: Find pathogenic variants in CFTR gene with expert panel review.
\nSteps:
\nCFTR[gene] AND clinsig_pathogenic[Properties] AND (\"reviewed by expert panel\"[Review status] OR \"practice guideline\"[Review status])\nObjective: Add clinical significance annotations to variant calls.
\nSteps:
\nwget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz\nwget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz.tbi\nbcftools annotate -a clinvar.vcf.gz \\\n -c INFO/CLNSIG,INFO/CLNDN,INFO/CLNREVSTAT \\\n -o annotated_variants.vcf \\\n your_variants.vcf\nbcftools view -i 'INFO/CLNSIG~\"Pathogenic\"' annotated_variants.vcf\nObjective: Study all variants associated with hereditary breast cancer.
\nSteps:
\n\"hereditary breast cancer\"[Disease/Phenotype] OR \"Breast-ovarian cancer, familial\"[Disease/Phenotype]\nObjective: Build a local ClinVar database for analysis pipeline.
\nSteps:
\nwget https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/ClinVarVCVRelease_YYYY-MM.xml.gz\n# previous years' monthly files move to xml/archive/<year>/\nThis skill includes comprehensive reference documentation:
\nreferences/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
For questions about ClinVar or data submission: clinvar@ncbi.nlm.nih.gov
\nscripts/query_clinvar.py — runnable helper for ClinVar via NCBI E-utilities (no key; NCBI_API_KEY lifts the rate limit):
python scripts/query_clinvar.py search \"BRCA1[gene] AND clinsig_pathogenic[Properties]\" --retmax 5\npython scripts/query_clinvar.py summary 12345,12346\n