Claude Skill

alterlab-clinvar

Query NCBI ClinVar via the E-utilities API or FTP for the clinical significance (pathogenicity) of human germline genetic variants, searching by gene, variant, condition, or genomic position and interpreting ACMG/AMP classifications and review-status star ratings. Use when assess

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download AlterLab-IEU-AlterLab-Academic-Skills-skills_databases_alterlab-clinvar-3ab6d03.zip · 23 KB

Install

skills CLI npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/databases/alterlab-clinvar
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
Git git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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
  • Interpreting clinical significance classifications (pathogenic, benign, VUS)
  • Accessing ClinVar data programmatically via E-utilities API
  • Downloading and processing bulk data from FTP
  • Understanding review status and star ratings
  • Resolving conflicting variant interpretations
  • Annotating variant call sets with clinical significance

Does NOT Trigger

Scenario Use Instead
Population allele frequency / ancestry-specific AF, gnomAD constraint alterlab-gnomad
Somatic cancer mutation catalog, Cancer Gene Census, mutational signatures alterlab-cosmic
How often a gene is mutated in tumor cohorts (TCGA, MSK-IMPACT) alterlab-cbioportal
Pharmacogenomic gene–drug dosing (CPIC/DPWG) alterlab-clinpgx

Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-gnomad) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.

Three classification types (since 2024). ClinVar now keeps separate aggregate classifications for germline pathogenicity (ACMG/AMP), somatic clinical impact (AMP/ASCO/CAP tiers), and oncogenicity (ClinGen/CGC/VICC). APIs and files expose them separately: esummary JSON has germline_classification, clinical_impact_classification, and oncogenicity_classification objects (each with description and review_status; there is no longer a clinical_significance field); the VCF has CLNSIG/CLNREVSTAT (germline), ONC/ONCREVSTAT, and SCI/SCIREVSTAT; variant_summary.txt has ClinicalSignificance (germline) plus SomaticClinicalImpact and Oncogenicity columns.

Core Capabilities

1. Search and Query ClinVar

Web Interface Queries

Search ClinVar using the web interface at https://www.ncbi.nlm.nih.gov/clinvar/

Common 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):

  • By gene: BRCA1[gene]
  • By clinical significance: 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)
  • By review status: "reviewed by expert panel"[Review status], "practice guideline"[Review status], "criteria provided, single submitter"[Review status]
  • By condition: "breast cancer"[Disease/Phenotype]
  • By variant: "c.1310_1313del"[Variant name]
  • By chromosome: 13[chr]
  • Combined: BRCA1[gene] AND clinsig_pathogenic[Properties]

Programmatic Access via E-utilities

Access ClinVar programmatically using NCBI's E-utilities API. Refer to references/api_reference.md for comprehensive API documentation including:

  • 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+clinsig_pathogenic[Properties]&retmode=json"

Always 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:

  • Test queries on the web interface before automating
  • Keyless access allows 3 requests/second; an optional NCBI_API_KEY raises it to 10
  • 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.

Key germline classification terms (ACMG/AMP):

  • Pathogenic (P) - Variant causes disease (~99% probability)
  • Likely Pathogenic (LP) - Variant likely causes disease (~90% probability)
  • Uncertain Significance (VUS) - Insufficient evidence to classify
  • Likely Benign (LB) - Variant likely does not cause disease
  • Benign (B) - Variant does not cause disease

Review status (star ratings):

  • ★★★★ Practice guideline - Highest confidence
  • ★★★ Expert panel review (e.g., ClinGen) - High confidence
  • ★★ Multiple submitters, no conflicts - Moderate confidence
  • ★ Criteria provided, single submitter — or criteria provided, conflicting classifications
  • ☆ No assertion criteria / no classification provided - Low confidence

Critical considerations:

  • Always check review status - prefer ★★★ or ★★★★ ratings
  • Conflicting interpretations require manual evaluation
  • Classifications may change as new evidence emerges
  • VUS (uncertain significance) variants lack sufficient evidence for clinical use

3. Download Bulk Data from FTP

Access ClinVar FTP Site

Download 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:

  • Monthly releases: First Thursday of each month (complete dataset, archived)
  • Weekly updates: Every Monday (incremental updates)

Available Formats

XML files (most comprehensive; current format since 2025-08-07, with separate germline / somatic elements):

  • VCV (Variation) files: xml/ClinVarVCVRelease_YYYY-MM.xml.gz (+ _00-latest symlink) - Variant-centric aggregation
  • RCV (Record) files: xml/RCV_release/ClinVarRCVRelease_YYYY-MM.xml.gz - Variant-condition pairs
  • The old ClinVarVariationRelease / ClinVarFullRelease formats (single classification element) are frozen in xml/VCV_xml_old_format/ and xml/RCV_xml_old_format/ and no longer supported
  • Include full submission details, evidence, and metadata

VCF files (for genomic pipelines):

  • GRCh37: vcf_GRCh37/clinvar.vcf.gz
  • GRCh38: vcf_GRCh38/clinvar.vcf.gz
  • Limitations: Excludes variants >10kb and complex structural variants

Tab-delimited files (for quick analysis):

  • tab_delimited/variant_summary.txt.gz - Summary of all variants
  • tab_delimited/var_citations.txt.gz - PubMed citations
  • tab_delimited/cross_references.txt.gz - Database cross-references

Example download:

# Download latest monthly VCV XML release
curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/ClinVarVCVRelease_00-latest.xml.gz

# Download VCF for GRCh38
curl -O https://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('ClinVarVCVRelease_00-latest.xml.gz', 'rt') as f:
    for event, elem in ET.iterparse(f, events=('end',)):
        if elem.tag == 'VariationArchive':
            variation_id = elem.attrib.get('VariationID')
            # Aggregate germline call lives under ClassifiedRecord/Classifications
            germline = elem.find('ClassifiedRecord/Classifications/GermlineClassification')
            if germline is not None:
                classification = germline.findtext('Description')      # e.g. "Pathogenic/Likely pathogenic"
                review_status = germline.findtext('ReviewStatus')
            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 pysam in Python (the old PyVCF/import vcf package is unmaintained and breaks on Python 3.10+; use pysam or cyvcf2 instead):

import pysam

vcf = pysam.VariantFile("clinvar.vcf.gz")
for rec in vcf:
    # CLNSIG is a comma/pipe-delimited string (e.g. "Pathogenic/Likely_pathogenic");
    # match as substring, not equality.
    clnsig = str(rec.info.get("CLNSIG", ""))
    if "Pathogenic" in clnsig:
        gene = rec.info.get("GENEINFO", "")
        print(f"{rec.chrom}:{rec.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 (one row per variant *per assembly* — keep one build,
# or every count is doubled)
df = pd.read_csv('variant_summary.txt.gz', sep='\t', compression='gzip', low_memory=False)
df = df[df['Assembly'] == 'GRCh38']

# 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 TP53 variants (GRCh38 rows). Columns: 3 Name, 5 GeneSymbol,
# 7 ClinicalSignificance (germline), 17 Assembly, 25 ReviewStatus, 31 VariationID
zcat variant_summary.txt.gz | \
  awk -F'\t' '$5=="TP53" && $7~/Pathogenic/ && $17=="GRCh38"' | \
  cut -f3,5,7,25,31

5. Handle Conflicting Interpretations

When 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:

  1. Check review status (star rating) - higher ratings carry more weight
  2. Examine evidence and assertion criteria from each submitter
  3. Consider submission dates - newer submissions may reflect updated evidence
  4. Review population frequency data (e.g., gnomAD) for context
  5. Consult expert panel classifications (★★★) when available
  6. For clinical use, always defer to a genetics professional

Search query to exclude conflicts:

TP53[gene] AND clinsig_pathogenic[Properties] NOT clinsig_has_conflicts[Properties]

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.

Submission methods:

Requirements:

  • Organizational account with NCBI
  • Assertion criteria (preferably ACMG/AMP guidelines)
  • Supporting evidence for classification

Contact: clinvar@ncbi.nlm.nih.gov for submission account setup.

Workflow Examples

Example 1: Identify High-Confidence Pathogenic Variants in a Gene

Objective: Find pathogenic variants in CFTR gene with expert panel review.

Steps:

  1. Search using web interface or E-utilities:
    CFTR[gene] AND clinsig_pathogenic[Properties] AND ("reviewed by expert panel"[Review status] OR "practice guideline"[Review status])
    
  2. Review results, noting review status (should be ★★★ or ★★★★)
  3. Export variant list or retrieve full records via efetch
  4. Cross-reference with clinical presentation if applicable

Example 2: Annotate VCF with ClinVar Classifications

Objective: Add clinical significance annotations to variant calls.

Steps:

  1. Download appropriate ClinVar VCF (match genome build: GRCh37 or GRCh38):
    curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz
    curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz.tbi
    
  2. Annotate using bcftools:
    bcftools annotate -a clinvar.vcf.gz \
      -c INFO/CLNSIG,INFO/CLNDN,INFO/CLNREVSTAT \
      -o annotated_variants.vcf \
      your_variants.vcf
    
  3. Filter annotated VCF for pathogenic variants:
    bcftools view -i 'INFO/CLNSIG~"Pathogenic"' annotated_variants.vcf
    

Example 3: Analyze Variants for a Specific Disease

Objective: Study all variants associated with hereditary breast cancer.

Steps:

  1. Search by condition:
    "hereditary breast cancer"[Disease/Phenotype] OR "Breast-ovarian cancer, familial"[Disease/Phenotype]
    
  2. Download results as CSV or retrieve via E-utilities
  3. Filter by review status to prioritize high-confidence variants
  4. Analyze distribution across genes (BRCA1, BRCA2, PALB2, etc.)
  5. Examine variants with conflicting interpretations separately

Example 4: Bulk Download and Database Construction

Objective: Build a local ClinVar database for analysis pipeline.

Steps:

  1. Download monthly release for reproducibility:
    curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/ClinVarVCVRelease_YYYY-MM.xml.gz
    # previous years' monthly files move to xml/archive/<year>/
    
  2. Parse XML and load into database (PostgreSQL, MySQL, MongoDB)
  3. Index by gene, position, clinical significance, review status
  4. Implement version tracking for updates
  5. Schedule monthly updates from FTP site

Important Limitations and Considerations

Data Quality

  • Not all submissions have equal weight - Check review status (star ratings)
  • Conflicting interpretations exist - Require manual evaluation
  • 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

External Resources

Contact

For questions about ClinVar or data submission: clinvar@ncbi.nlm.nih.gov

Scripts

scripts/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
python scripts/query_clinvar.py summary 12345,12346
Files (alterlab-academic-skills)
  • evals
    • fixtures
      • patient_PT-0193.GRCh38.vcf 1.8 KB · in bundle
    • evals.json 5.9 KB
      Loading…
  • references
    • api_reference.md 7.5 KB
      Loading…
    • clinical_significance.md 9.9 KB
      Loading…
    • data_formats.md 12.5 KB
      Loading…
  • scripts
    • query_clinvar.py 2.4 KB
      Loading…
  • SKILL.md 17.9 KB
    ---
    name: alterlab-clinvar
    description: Query NCBI ClinVar via the E-utilities API or FTP for the clinical significance (pathogenicity) of human germline genetic variants, searching by gene, variant, condition, or genomic position and interpreting ACMG/AMP classifications and review-status star ratings. Use when assessing whether a variant is pathogenic, likely pathogenic, VUS, likely benign, or benign, resolving conflicting interpretations, or annotating a VCF with ClinVar clinical significance. For population allele frequencies by ancestry use alterlab-gnomad; for somatic cancer mutation frequencies use alterlab-cosmic. Part of the AlterLab Academic Skills suite.
    license: MIT
    allowed-tools: Read WebFetch Bash(curl:*) Bash(python:*)
    compatibility: No API key required. Keyless NCBI E-utilities REST API (db=clinvar, 3 requests/s per IP) and the public ClinVar FTP; an optional NCBI_API_KEY raises the limit to 10 requests/s
    metadata:
        skill-author: AlterLab
        version: "1.1.1"
        last_updated: "2026-10-22"
        credentials: "optional: NCBI_API_KEY (raises E-utilities from 3 to 10 requests/s)"
    ---
    
    # 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
    - Interpreting clinical significance classifications (pathogenic, benign, VUS)
    - Accessing ClinVar data programmatically via E-utilities API
    - Downloading and processing bulk data from FTP
    - Understanding review status and star ratings
    - Resolving conflicting variant interpretations
    - Annotating variant call sets with clinical significance
    
    ### Does NOT Trigger
    
    | Scenario | Use Instead |
    |----------|-------------|
    | Population allele frequency / ancestry-specific AF, gnomAD constraint | `alterlab-gnomad` |
    | Somatic cancer mutation catalog, Cancer Gene Census, mutational signatures | `alterlab-cosmic` |
    | How often a gene is mutated in tumor cohorts (TCGA, MSK-IMPACT) | `alterlab-cbioportal` |
    | Pharmacogenomic gene–drug dosing (CPIC/DPWG) | `alterlab-clinpgx` |
    
    **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-gnomad`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
    
    **Three classification types (since 2024).** ClinVar now keeps separate aggregate
    classifications for **germline** pathogenicity (ACMG/AMP), **somatic clinical impact**
    (AMP/ASCO/CAP tiers), and **oncogenicity** (ClinGen/CGC/VICC). APIs and files expose them
    separately: esummary JSON has `germline_classification`, `clinical_impact_classification`,
    and `oncogenicity_classification` objects (each with `description` and `review_status`;
    there is no longer a `clinical_significance` field); the VCF has `CLNSIG`/`CLNREVSTAT`
    (germline), `ONC`/`ONCREVSTAT`, and `SCI`/`SCIREVSTAT`; `variant_summary.txt` has
    `ClinicalSignificance` (germline) plus `SomaticClinicalImpact` and `Oncogenicity` columns.
    
    ## Core Capabilities
    
    ### 1. Search and Query ClinVar
    
    #### Web Interface Queries
    
    Search ClinVar using the web interface at https://www.ncbi.nlm.nih.gov/clinvar/
    
    **Common 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):
    - By gene: `BRCA1[gene]`
    - By clinical significance: `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)
    - By review status: `"reviewed by expert panel"[Review status]`, `"practice guideline"[Review status]`, `"criteria provided, single submitter"[Review status]`
    - By condition: `"breast cancer"[Disease/Phenotype]`
    - By variant: `"c.1310_1313del"[Variant name]`
    - By chromosome: `13[chr]`
    - Combined: `BRCA1[gene] AND clinsig_pathogenic[Properties]`
    
    #### Programmatic Access via E-utilities
    
    Access ClinVar programmatically using NCBI's E-utilities API. Refer to `references/api_reference.md` for comprehensive API documentation including:
    - **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:**
    ```bash
    # Search for pathogenic BRCA1 variants
    curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term=BRCA1[gene]+AND+clinsig_pathogenic[Properties]&retmode=json"
    ```
    Always 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:**
    - Test queries on the web interface before automating
    - Keyless access allows 3 requests/second; an optional `NCBI_API_KEY` raises it to 10
    - 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.
    
    **Key germline classification terms (ACMG/AMP):**
    - **Pathogenic (P)** - Variant causes disease (~99% probability)
    - **Likely Pathogenic (LP)** - Variant likely causes disease (~90% probability)
    - **Uncertain Significance (VUS)** - Insufficient evidence to classify
    - **Likely Benign (LB)** - Variant likely does not cause disease
    - **Benign (B)** - Variant does not cause disease
    
    **Review status (star ratings):**
    - ★★★★ Practice guideline - Highest confidence
    - ★★★ Expert panel review (e.g., ClinGen) - High confidence
    - ★★ Multiple submitters, no conflicts - Moderate confidence
    - ★ Criteria provided, single submitter — or criteria provided, conflicting classifications
    - ☆ No assertion criteria / no classification provided - Low confidence
    
    **Critical considerations:**
    - Always check review status - prefer ★★★ or ★★★★ ratings
    - Conflicting interpretations require manual evaluation
    - Classifications may change as new evidence emerges
    - VUS (uncertain significance) variants lack sufficient evidence for clinical use
    
    ### 3. Download Bulk Data from FTP
    
    #### Access ClinVar FTP Site
    
    Download 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:**
    - Monthly releases: First Thursday of each month (complete dataset, archived)
    - Weekly updates: Every Monday (incremental updates)
    
    #### Available Formats
    
    **XML files** (most comprehensive; current format since 2025-08-07, with separate germline / somatic elements):
    - VCV (Variation) files: `xml/ClinVarVCVRelease_YYYY-MM.xml.gz` (+ `_00-latest` symlink) - Variant-centric aggregation
    - RCV (Record) files: `xml/RCV_release/ClinVarRCVRelease_YYYY-MM.xml.gz` - Variant-condition pairs
    - The old `ClinVarVariationRelease` / `ClinVarFullRelease` formats (single classification element) are frozen in `xml/VCV_xml_old_format/` and `xml/RCV_xml_old_format/` and no longer supported
    - Include full submission details, evidence, and metadata
    
    **VCF files** (for genomic pipelines):
    - GRCh37: `vcf_GRCh37/clinvar.vcf.gz`
    - GRCh38: `vcf_GRCh38/clinvar.vcf.gz`
    - Limitations: Excludes variants >10kb and complex structural variants
    
    **Tab-delimited files** (for quick analysis):
    - `tab_delimited/variant_summary.txt.gz` - Summary of all variants
    - `tab_delimited/var_citations.txt.gz` - PubMed citations
    - `tab_delimited/cross_references.txt.gz` - Database cross-references
    
    **Example download:**
    ```bash
    # Download latest monthly VCV XML release
    curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/ClinVarVCVRelease_00-latest.xml.gz
    
    # Download VCF for GRCh38
    curl -O https://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:**
    ```python
    import gzip
    import xml.etree.ElementTree as ET
    
    with gzip.open('ClinVarVCVRelease_00-latest.xml.gz', 'rt') as f:
        for event, elem in ET.iterparse(f, events=('end',)):
            if elem.tag == 'VariationArchive':
                variation_id = elem.attrib.get('VariationID')
                # Aggregate germline call lives under ClassifiedRecord/Classifications
                germline = elem.find('ClassifiedRecord/Classifications/GermlineClassification')
                if germline is not None:
                    classification = germline.findtext('Description')      # e.g. "Pathogenic/Likely pathogenic"
                    review_status = germline.findtext('ReviewStatus')
                elem.clear()  # Free memory
    ```
    
    #### Working with VCF Files
    
    Annotate variant calls or filter by clinical significance using bcftools or Python.
    
    **Using bcftools:**
    ```bash
    # 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 pysam in Python** (the old `PyVCF`/`import vcf` package is unmaintained and breaks on Python 3.10+; use `pysam` or `cyvcf2` instead):
    ```python
    import pysam
    
    vcf = pysam.VariantFile("clinvar.vcf.gz")
    for rec in vcf:
        # CLNSIG is a comma/pipe-delimited string (e.g. "Pathogenic/Likely_pathogenic");
        # match as substring, not equality.
        clnsig = str(rec.info.get("CLNSIG", ""))
        if "Pathogenic" in clnsig:
            gene = rec.info.get("GENEINFO", "")
            print(f"{rec.chrom}:{rec.pos} {gene} - {clnsig}")
    ```
    
    #### Working with Tab-Delimited Files
    
    Use pandas or command-line tools for rapid filtering and analysis.
    
    **Using pandas:**
    ```python
    import pandas as pd
    
    # Load variant summary (one row per variant *per assembly* — keep one build,
    # or every count is doubled)
    df = pd.read_csv('variant_summary.txt.gz', sep='\t', compression='gzip', low_memory=False)
    df = df[df['Assembly'] == 'GRCh38']
    
    # 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:**
    ```bash
    # Extract pathogenic TP53 variants (GRCh38 rows). Columns: 3 Name, 5 GeneSymbol,
    # 7 ClinicalSignificance (germline), 17 Assembly, 25 ReviewStatus, 31 VariationID
    zcat variant_summary.txt.gz | \
      awk -F'\t' '$5=="TP53" && $7~/Pathogenic/ && $17=="GRCh38"' | \
      cut -f3,5,7,25,31
    ```
    
    ### 5. Handle Conflicting Interpretations
    
    When 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:**
    1. Check review status (star rating) - higher ratings carry more weight
    2. Examine evidence and assertion criteria from each submitter
    3. Consider submission dates - newer submissions may reflect updated evidence
    4. Review population frequency data (e.g., gnomAD) for context
    5. Consult expert panel classifications (★★★) when available
    6. For clinical use, always defer to a genetics professional
    
    **Search query to exclude conflicts:**
    ```
    TP53[gene] AND clinsig_pathogenic[Properties] NOT clinsig_has_conflicts[Properties]
    ```
    
    ### 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.
    
    **Submission methods:**
    - Web submission portal: https://submit.ncbi.nlm.nih.gov/clinvar/
    - API submission (requires service account): See `references/api_reference.md`
    - Batch submission via Excel templates
    
    **Requirements:**
    - Organizational account with NCBI
    - Assertion criteria (preferably ACMG/AMP guidelines)
    - Supporting evidence for classification
    
    Contact: clinvar@ncbi.nlm.nih.gov for submission account setup.
    
    ## Workflow Examples
    
    ### Example 1: Identify High-Confidence Pathogenic Variants in a Gene
    
    **Objective:** Find pathogenic variants in CFTR gene with expert panel review.
    
    **Steps:**
    1. Search using web interface or E-utilities:
       ```
       CFTR[gene] AND clinsig_pathogenic[Properties] AND ("reviewed by expert panel"[Review status] OR "practice guideline"[Review status])
       ```
    2. Review results, noting review status (should be ★★★ or ★★★★)
    3. Export variant list or retrieve full records via efetch
    4. Cross-reference with clinical presentation if applicable
    
    ### Example 2: Annotate VCF with ClinVar Classifications
    
    **Objective:** Add clinical significance annotations to variant calls.
    
    **Steps:**
    1. Download appropriate ClinVar VCF (match genome build: GRCh37 or GRCh38):
       ```bash
       curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz
       curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz.tbi
       ```
    2. Annotate using bcftools:
       ```bash
       bcftools annotate -a clinvar.vcf.gz \
         -c INFO/CLNSIG,INFO/CLNDN,INFO/CLNREVSTAT \
         -o annotated_variants.vcf \
         your_variants.vcf
       ```
    3. Filter annotated VCF for pathogenic variants:
       ```bash
       bcftools view -i 'INFO/CLNSIG~"Pathogenic"' annotated_variants.vcf
       ```
    
    ### Example 3: Analyze Variants for a Specific Disease
    
    **Objective:** Study all variants associated with hereditary breast cancer.
    
    **Steps:**
    1. Search by condition:
       ```
       "hereditary breast cancer"[Disease/Phenotype] OR "Breast-ovarian cancer, familial"[Disease/Phenotype]
       ```
    2. Download results as CSV or retrieve via E-utilities
    3. Filter by review status to prioritize high-confidence variants
    4. Analyze distribution across genes (BRCA1, BRCA2, PALB2, etc.)
    5. Examine variants with conflicting interpretations separately
    
    ### Example 4: Bulk Download and Database Construction
    
    **Objective:** Build a local ClinVar database for analysis pipeline.
    
    **Steps:**
    1. Download monthly release for reproducibility:
       ```bash
       curl -O https://ftp.ncbi.nlm.nih.gov/pub/clinvar/xml/ClinVarVCVRelease_YYYY-MM.xml.gz
       # previous years' monthly files move to xml/archive/<year>/
       ```
    2. Parse XML and load into database (PostgreSQL, MySQL, MongoDB)
    3. Index by gene, position, clinical significance, review status
    4. Implement version tracking for updates
    5. Schedule monthly updates from FTP site
    
    ## Important Limitations and Considerations
    
    ### Data Quality
    - **Not all submissions have equal weight** - Check review status (star ratings)
    - **Conflicting interpretations exist** - Require manual evaluation
    - **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
    
    ### External Resources
    
    - ClinVar home: https://www.ncbi.nlm.nih.gov/clinvar/
    - ClinVar documentation: https://www.ncbi.nlm.nih.gov/clinvar/docs/help/
    - E-utilities documentation: https://www.ncbi.nlm.nih.gov/books/NBK25501/
    - ACMG variant interpretation guidelines: Richards et al., 2015 (PMID: 25741868)
    - ClinGen expert panels: https://clinicalgenome.org/
    
    ### Contact
    
    For questions about ClinVar or data submission: clinvar@ncbi.nlm.nih.gov
    
    ## Scripts
    
    `scripts/query_clinvar.py` — runnable helper for ClinVar via NCBI E-utilities (no key; `NCBI_API_KEY` lifts the rate limit):
    
    ```bash
    python scripts/query_clinvar.py search "BRCA1[gene] AND clinsig_pathogenic[Properties]" --retmax 5
    python scripts/query_clinvar.py summary 12345,12346
    ```
    
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.