Dbsnp Database

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 .licenses/dbsnp_database_LICENSE.txt does not already exist in the workspace root 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. You can register for a key for free at https://www.ncbi.nlm.nih.gov/account/settings/. You MUST use the safe credentials protocol in the credentials skill to check for and request this key if this skill looks relevant to the user's request.

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

# 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.

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).
• --full: Return the complete raw JSON payload — see warning below.
• --output: Output file path (default: /tmp/dbsnp_output.json).

Abbreviated output fields:

• refsnp_id: Numeric rsID
• variant_type: e.g. snv, ins, del, delins
• genes: Sorted list of gene symbols (locus names)
• clinical_significances: List of clinical significance labels
• minor_allele_frequencies: Study name, allele count, total count
• placements: Genomic placements for the requested assembly

[!WARNING] About `--full`: The raw RefSNP payload is typically 50–500 KB and can exceed 1 MB for clinically significant variants with many submissions. Only use --full when you specifically need data absent from the abbreviated output — for example: - The complete HGVS nomenclature across every transcript and protein isoform. - Full submission history with individual submitter details and timestamps. - Population-level allele frequency breakdowns by sub-population within a study (e.g. per-population gnomAD counts). - The full set of genomic placements across multiple assemblies (GRCh37 and GRCh38 simultaneously). - Merge history showing which older rsIDs were merged into this one.

2. resolve-variant — Genomic Coordinates → rsID

Determine the rsID(s) for a variant given its genomic coordinates (chromosome, position, reference allele, alternate allele). This is the command to use when the user provides a variant as space-separated coordinates like 8 19962213 C T.

uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T \
  --output /tmp/resolve.json

Arguments:

• chrom (positional): Chromosome number (e.g. 8) or RefSeq sequence accession (e.g. NC_000008.11). Chromosomes X and Y must be passed as their numeric equivalents: `23` for X and `24` for Y.
• pos (positional): 1-based genomic position.
• ref (positional): Reference allele (e.g. C).
• alts (positional): Alternate allele(s), comma-separated (e.g. T).
• --assembly: RefSeq assembly accession (default: GCF_000001405.40).
• --output: Output file path (default: /tmp/dbsnp_output.json).

Output: {"rsids": ["12345", "67890"]}

3. resolve-rsid — rsID → Genomic Coordinates

Get the genomic placement (sequence ID and allele details) for a known rsID on a specific assembly.

uv run scripts/dbsnp_cli.py resolve-rsid rs7412 --output /tmp/coords.json

Arguments:

• rsid (positional): The RefSNP identifier.
• --assembly: RefSeq assembly accession (default: GCF_000001405.40).
• --output: Output file path (default: /tmp/dbsnp_output.json).

Output: {"rsid": "7412", "assembly": "...", "placements": [...]}

4. resolve-hgvs — HGVS → rsID

Find the rsID(s) corresponding to an HGVS expression.

uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000008.11:g.19962213del' \
  --output /tmp/hgvs.json

Arguments:

• hgvs (positional): The HGVS string.
• --assembly: RefSeq assembly accession (default: GCF_000001405.40).
• --output: Output file path (default: /tmp/dbsnp_output.json).

Output: {"rsids": ["12345"]}

[!TIP] HGVS strings often contain characters that shells interpret (colons, greater-than signs). Always wrap them in single quotes to prevent shell expansion.

5. search-region — Regional Variant Search