---
name: clinvar-database-3d19314ee7d8
description: Utilities for querying the NCBI ClinVar database to retrieve variant records, clinical significance, and phenotype relationships; use when searching variants by gene/condition/significance, interpreting Pathogenic/Benign/VUS classifications, or annotating VCF files with ClinVar annotations.
license: MIT
author: AIPOCH
---
> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)

## When to Use

- You need to find ClinVar variant records by **gene**, **condition/phenotype**, or **clinical significance** (e.g., *BRCA1* + *pathogenic*).
- You want to interpret a variant’s **clinical significance** (Pathogenic/Benign/VUS) and **review status** for reporting or triage.
- You need to **annotate a VCF** with ClinVar identifiers and interpretation fields as part of a variant annotation pipeline.
- You want to perform **bulk retrieval** of ClinVar datasets for offline analysis or periodic database refresh.
- You are building a workflow that relies on **NCBI E-utilities** to programmatically query ClinVar.

## Key Features

- **ClinVar search** via NCBI E-utilities using flexible query terms (gene/condition/significance).
- **Clinical interpretation retrieval**, including clinical significance categories and review status.
- **VCF annotation** workflow integration (leveraging `bcftools`) to enrich variants with ClinVar data.
- **Bulk data access** through ClinVar FTP downloads for large-scale processing.
- Reference documentation:
  - API details: `references/api_reference.md`
  - Clinical significance definitions: `references/clinical_significance.md`

## Dependencies

- Python `>=3.8`
- `requests` (Python package)
- `bcftools` (system dependency; required for VCF annotation)
- `pandas` (Python package; optional for downstream data processing)

## Example Usage

### 1) Search ClinVar for pathogenic variants in a gene

```bash
python scripts/search.py --term "BRCA1[gene] AND pathogenic[CLNSIG]"
```

### 2) Annotate a VCF with ClinVar data

```bash
python scripts/annotate.py --input input.vcf --output annotated.vcf
```

## Implementation Details

- **Search (`scripts/search.py`)**
  - Uses **NCBI E-utilities** to query ClinVar with a user-provided `--term`.
  - The query term supports ClinVar/Entrez syntax (e.g., `BRCA1[gene]`, `pathogenic[CLNSIG]`) to filter by gene and clinical significance.
  - Output is expected to include matching ClinVar records/identifiers suitable for follow-up interpretation or annotation.

- **Interpretation fields**
  - Clinical significance values (e.g., Pathogenic/Benign/VUS) and related interpretation guidance follow ClinVar conventions; see `references/clinical_significance.md`.
  - Review status (e.g., level of evidence/review) is retrieved alongside significance where available.

- **VCF annotation (`scripts/annotate.py`)**
  - Takes an input VCF (`--input`) and produces an annotated VCF (`--output`).
  - Integrates with `bcftools` to add ClinVar-derived annotations to variant records (requires `bcftools` installed and available on `PATH`).
  - Designed for pipeline use: deterministic input/output files and command-line parameters.

- **Bulk downloads**
  - Supports obtaining ClinVar datasets via FTP for offline indexing/annotation workflows.
  - Recommended when you need reproducible, high-throughput annotation without repeated API calls.

---
Source attribution: aipoch
Original project: https://github.com/aipoch/medical-research-skills/blob/686e09dfdb45d9fa1a08664f06bb93769b3c9d91/scientific-skills/Evidence%20Insight/clinvar-database/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 AIpoch

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: aipoch
Original project: https://github.com/aipoch/medical-research-skills/blob/686e09dfdb45d9fa1a08664f06bb93769b3c9d91/scientific-skills/Evidence%20Insight/clinvar-database/SKILL.md
Attribution basis: Source repository record

Fields of work: Data & Analytics, Education & Research, Healthcare & Life Sciences
Roles: Clinical Research, Data Scientist, Researcher
Specialties: API, Cross Platform, Database
Tools: Bcftools, Requests
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 2a4ba2fdc70118fc78db45a1f665ce24c8798a27af40604c6feb3f46486afda9