dbsnp-database

Files (3)

• SKILL.md
• api-notes.md · references/
• dbsnp_cli.py · scripts/

SKILL.md (first lines)

# dbSNP Database Integration

## 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/snp/, 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](#ncbi-api-key-and-rate-limiting) for more details.

## Core Rules

-   **Use the Wrapper**: ALWAYS execute the provided wrapper script
    `scripts/dbsnp_cli.py` to query the database rather than constructing custom
    HTTP or curl requests. The script automatically handles rate limiting,
    retries, and JSON parsing.
-   **Command Choice**: Do NOT use `search-region` to find the rsID of a
    specific variant; use `resolve-variant` instead.
-   **Output Size**: Avoid using `--full` on `get-variant` unless specifically
    needed, as raw payloads can exceed 1 MB.
-   **Shell Safety**: Always wrap HGVS strings in single quotes to prevent shell
    expansion errors.
-   **Notification**: If this skill is used, ensure this is mentioned in the
    output.

## When to Use

**Use this skill when you need to:**

-   Map a genomic variant to its canonical rsID (from VCF coordinates or HGVS
    notation).
-   Retrieve summary data for an rsID: variant type, gene associations, clinical
    significance, and population allele frequencies.
-   Convert an rsID back to genomic coordinates on a specific assembly.
-   Find all known variants within a chromosomal region.

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

-   Obtain clinical pathogenicity classifications with submitter rationales (use
    **clinvar-database**).
-   Get precise population-level allele frequencies stratified by ancestry (use
    **gnomad-database**).
-   Predict the functional effect of a novel mutation (use
    **alphagenome-single-variant-analysis**).
-   View 3D protein structures affected by a variant (use
    **alphafold-database-fetch-and-analyze / pdb-database**).

## Command Selection Guide

**Pick the right command on the first try.** Match the user's input to the
correct subcommand below — one command call is almost always sufficient.

-   User gives you…: Run this command
-   An rsID (e.g. `rs7412`, `rs268`): `get-variant`
-   Genomic coordinates: chrom pos ref alt (e.g. `8 19962213 C T`):
    `resolve-variant`
-   An HGVS string (e.g. `NC_000008.11:g.19962213del`): `resolve-hgvs`
-   An rsID and they want coordinates back: `resolve-rsid`
-   A chromosomal region (chrom start end): `search-region`

> [!CAUTION] **Do NOT use `search-region` to find the rsID of a specific
> variant.** If the user provides a chromosome, position, reference allele, and
> alternate allele (four values), use `resolve-variant` — it is a direct,
> single-API-call lookup. `search-region` is only for surveying all variants
> within a positional range and returns hundreds/thousands of results.

## Quick Start

```bash
# Look up variant rs7412: type, gene, clinical significance, MAF
uv run scripts/dbsnp_cli.py get-variant rs7412 --output /tmp/rs7412.json

# Find the rsID for a variant at chr8:19962213 C>T
uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json
```

All subcommands write JSON to disk. Always save output in the `/tmp/` directory.
The `--output` flag is required.

## Commands

### 1. `get-variant` — Fetch Variant Record

Retrieve the RefSNP record for one rsID. By default the output is abbreviated to
the most useful fields. Both `rs268` and `268` are accepted.

```bash
uv run scripts/dbsnp_cli.py get-variant rs268 --output /tmp/rs268.json
uv run scripts/dbsnp_cli.py get-variant 268 --assembly GCF_000001405.40 \
  --output /tmp/rs268.json
```

*Arguments:*

-   `rsid` (positional, required): The RefSNP identifier.
-   `--assembly`: RefSeq assembly accession (default: `GCF_000001405.40` =
    GRCh38).

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

More from hanyanphysics/AI-for-Physics