bio-clinical-databases-dbsnp-queries

What it does

Resolves rsIDs, traverses RsMergeArch/SNPHistory chains, and converts among rsID, SPDI, HGVS, and VCF representations using the dbSNP Build 156 JSON architecture. Use when normalizing variant identifiers, joining variant databases by cluster ID, or tracking deprecated rsIDs through historical merges.

How it works

• Provides methods to fetch full Build 156 RefSNP JSON via Variation Services /v0/refsnp/{id}, extracting current and merged data.
• Includes functions to resolve multi-hop merge chains by following merged_snapshot_data and detecting cycles.
• Demonstrates SPDI, HGVS, and VCF conversion pathways through canonicalization endpoints, contextual HGVS, and SPDI mappings.
• Uses explicit Python examples for:
  • RefSNP fetch: Variation Services /v0/refsnp/{id}
  • Multi-hop resolution via merged_snapshot_data
  • SPDI ↔ rsID lookups, HGVS contextuals, and VCF-to-SPDI canonicalization
  • ALFA/gnomAD frequency lookups via Variation Services

When to use it

• To resolve a single rsID to coordinates and alleles with full Build 156 data
• To resolve historical/deprecated rsIDs by following merge history
• To perform bulk rsID normalization, or convert between representations for joins across databases
• To convert between SPDI, HGVS, and VCF representations using the canonical bridge

What it can touch

• Variation Services REST API at https://api.ncbi.nlm.nih.gov/variation/v0
• SPDI/HGVS/VCF conversion endpoints under Variation Services
• Local JSON parsing structures for primary_snapshot_data and merged_snapshot_data

Caveats

• Build 156 is JSON-only; Build 151 used relational SQL dumps. E-utilities db=snp may return a thin pre-156 summary missing key fields.
• rsID is a cluster identifier, not a single-variant ID; multi-allelic sites are common (~6-8%).
• Withdrawal data live in SNPHistory.bcp.gz, not RsMergeArch.
• The sample code includes cycle detection for merge chains and warns about potential stale IDs if not followed through the full chain.