annotating-variants

Annotating variants & normalizing HGVS

Turn raw genomic variants — VCF rows, rsIDs, or HGVS strings — into annotated, consequence-predicted records, and link them to the clinical context OpenMed extracts from text (genes, variants, oncology findings, phenotype). The workhorse for a quick, no-install annotation is the Ensembl VEP REST API; for scale, run VEP, SnpEff, or ANNOVAR offline.

These annotators are free and license-permissive. Restricted clinical interpretation databases (e.g. licensed HGMD) are user-supplied — this skill sticks to open resources (Ensembl, gnomAD, ClinVar).

When to use

• You have a VCF / HGVS / rsID and need consequence predictions (missense, stop-gain, splice), affected transcripts, and protein change.
• You need to normalize HGVS to genomic coordinates (and back) on a known build (GRCh38 by default; GRCh37 via the dedicated endpoint).
• You want gnomAD population allele frequencies to flag common vs rare.
• You are pairing molecular findings with the phenotype/oncology context that OpenMed pulls from notes or literature.

Quick start (real Ensembl VEP REST call)

Base URL: https://rest.ensembl.org (GRCh38). For GRCh37 use https://grch37.rest.ensembl.org. Default species is human/homo_sapiens.

import requests

REST = "https://rest.ensembl.org"
HEADERS = {"Content-Type": "application/json", "Accept": "application/json"}

def vep_hgvs(hgvs: str) -> list[dict]:
    """Annotate a single HGVS variant (GET)."""
    r = requests.get(f"{REST}/vep/human/hgvs/{hgvs}", headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()

# Transcript-level HGVS (coding) — note the build-aware default transcript set
ann = vep_hgvs("ENST00000269305.9:c.215C>G")   # TP53 example
v = ann[0]
print(v["most_severe_consequence"])            # e.g. "missense_variant"
for tc in v.get("transcript_consequences", []):
    print(tc["gene_symbol"], tc.get("hgvsp"), tc.get("sift_prediction"),
          tc.get("polyphen_prediction"))