clinvar-database

Files (2)

• SKILL.md
• clinvar_api.py · scripts/

SKILL.md (first lines)

# ClinVar Database

## Prerequisites

1.  **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
    `uv` is installed and on PATH.
2.  **User Notification**: If LICENSE_NOTIFICATION.txt does not already exist in
    this skill directory then (1) prominently notify the user to check the terms
    at https://www.ncbi.nlm.nih.gov/clinvar/, then (2) create the file recording
    the notification text and timestamp.
3.  **`.env` file**: Make sure the `.env` file exists in your home directory.
    Create one if it does not exist.
4.  **`NCBI_API_KEY`** (optional): Raises the NCBI rate limit from 3 to 10
    requests/second. The skill works without it, but a key is recommended if the
    user plans many queries or encounters a 429 error. The user can obtain one
    for free by registering at https://www.ncbi.nlm.nih.gov/account/settings/.
    If the variable is missing from `.env`, do NOT ask the user to paste it into
    the chat (this would leak the key into the agent's context). Instead, give
    the user this command — **substituting `ENV_FILE` with the resolved literal
    path to the `.env` file**:

    ```bash
    printf "Enter NCBI API key (typing hidden): " && read -s key && echo && echo "NCBI_API_KEY=$key" >> "ENV_FILE" && echo "Saved."
    ```

    The scripts load credentials automatically via `dotenv`. **NEVER** read,
    print, or inspect the `.env` file or its variables (e.g. no `cat`, `grep`,
    `echo`, `printenv`, or `os.environ.get` on keys). Credentials must stay out
    of the agent's context. See the
    [API Key section](#obtaining-and-using-an-api-key) for more details.

## Overview

ClinVar is the primary consensus record for clinical classifications of human
genomic variations. It provides the "clinical ground truth" for pathogenicity
labels (Pathogenic, Likely Pathogenic, Benign, VUS) based on assertions from
global laboratories.

## When to Use

**Use when you need to:**

-   Find the current clinical significance and star rating (review status) for a
    specific variant.
-   Fetch clinician notes, assertion criteria, or rationales for previous
    clinical laboratory classifications.
-   Retrieve the preferred condition name and associated HPO terms for a
    specific variant.
-   Find a list of variant controls (e.g., "Find all Pathogenic variants in the
    HBB gene within 50bp of a signal").
-   Check for conflicting interpretations for a given variant and identify the
    organizations submitting each classification.

**Do NOT use when you need to:**

-   Find specific allele frequencies in global populations (use **gnomAD**).
-   Describe the normal biological role of a protein and typical inheritance
    patterns (use **OMIM**).
-   Predict mechanistic effects of novel mutations, like frameshifts or exon
    skipping (use **AlphaGenome**).
-   Find recommended surveillance schedules for patients with a pathogenic
    variant (use **GeneReviews**).
-   Generate or view 3D structural models of affected proteins (use **PDB /
    AlphaFold**).

## Quick Start

ClinVar queries are executed via a robust Python wrapper script to handle strict
rate limiting and XML/JSON parsing.

Example: Search for BRCA1 variants

```bash
uv run scripts/clinvar_api.py search --query "BRCA1[gene]" --output results.json
```

## Core Rules

-   **Retmax Constraint**: The search command defaults to `--retmax 200`. For
    any "List all" or gene-wide request, you MUST explicitly set `--retmax`
    higher (e.g., 1000) to ensure data completeness.
-   **Use the Wrapper**: Prefer the wrapper script for standard queries. It
    handles rate limiting, retries, and the complex XML parsing for you. If the
    script's parsed output does not contain the specific fields you need, you
    may modify the script or query the NCBI E-utilities API directly — but be
    aware that the raw XML schemas are complex and vary between record types.
-   If the rate limit is hit, the script will throw a clear error. Follow the
    prerequisite instructions above to help the user add `NCBI_API_KEY` to the
    `.env` file.
-   **Notification**: If this skill is used, ensure this is mentioned in the
    output.

## Utility Scripts

### 1. `count` — Count Matching Variants

**Purpose:** Check how many variants match a query without fetching IDs. Use to
decide whether a full `search` is warranted.

*Arguments:*

-   `--query`: (Required) NCBI Entrez search query string.
-   `--output`: (Required) Output JSON file path.

*Example:* `uv run scripts/clinvar_api.py count \ --query "TP53[gene] AND
\"uncertain significance\"[clinsig]" \ --output count.json` *Output:*
`{"total_count": <int>}`

### 2. `search` — Search Variants

**Purpose:** Identify variants based on genomic location, gene symbols, or
clinical attributes using NCBI Entrez search syntax. The search command
**automatically paginates** through all matching results to ensure complete,
deterministic retrieval.

```bash
# Fetch ALL matching variants (default behavior)
uv run scripts/clinvar_api.py search \
  --query "BRCA1[gene]" --output results.json

From hanyanphysics/AI-for-Physics, Apache-2.0.

More from hanyanphysics/AI-for-Physics