Skip to content

7. Translating Uncertain-Range HGVS Expressions

ClinVar often reports copy-number variants (CNVs) with imprecise breakpoints, written in HGVS as nested parenthesized ranges:

  • Balanced uncertainty on both sides: g.(A_B)_(C_D)del — the left breakpoint is somewhere between positions A and B (inclusive); the right breakpoint is somewhere between C and D.
  • One-sided unknown: g.(?_N)_(M_?)del — the outer bound on one side is unknown.

VRS 2.x represents this directly: SequenceLocation.start / end can be a Range (a 2-element list of integers, with None allowed for ?) rather than a single int. This notebook walks through parsing the ClinVar expressions from biocommons/hgvs#225 via CnvTranslator, and round-tripping a VRS object with a Range location back to HGVS via AlleleTranslator.

Requirements: hgvs>=2.0.0a0 (which parses uncertain-range expressions). The reverse from_hgvs path for AlleleTranslator intentionally raises ValueError for uncertain ranges, since LiteralSequenceExpression cannot represent an unknown reference; use CnvTranslator for those del/dup cases.

Setup

We use a SeqRepo data proxy (local or REST) and a UTA connection for the HGVS library. Substitute your own URIs as needed.

In [1]
import os

os.environ.setdefault(
    "UTA_DB_URL",
    "postgresql://anonymous:anonymous@uta.biocommons.org:5432/uta/uta_20241220",
)

from ga4gh.vrs import models
from ga4gh.vrs.dataproxy import create_dataproxy
from ga4gh.vrs.extras.translator import AlleleTranslator, CnvTranslator

seqrepo_uri = os.environ.get(
    "SEQREPO_URI", "seqrepo+https://services.genomicmedlab.org/seqrepo"
)
dp = create_dataproxy(uri=seqrepo_uri)
cnv_tlr = CnvTranslator(data_proxy=dp, default_assembly_name="GRCh38", identify=True)
allele_tlr = AlleleTranslator(
    data_proxy=dp, default_assembly_name="GRCh38", identify=True
)

Example 1 — Balanced uncertain range (dup)

ClinVar variation 251062 on GRCh37:

NC_000019.9:g.(11211022_11213339)_(11217364_11218067)dup

The left breakpoint is somewhere in [11211022, 11213339] and the right is somewhere in [11217364, 11218067]. The resulting SequenceLocation carries a Range for both start and end.

In [2]
cnc = cnv_tlr.to_vrs(
    "NC_000019.9:g.(11211022_11213339)_(11217364_11218067)dup", "hgvs"
)
cnc.model_dump(exclude_none=True)

Output:

{'id': 'ga4gh:CX.fNeJdvcthBYmbtK4TWVbQQwS-jGSsLXd',
 'type': 'CopyNumberChange',
 'digest': 'fNeJdvcthBYmbtK4TWVbQQwS-jGSsLXd',
 'location': {'id': 'ga4gh:SL.ZFKeEaewVWHpvfvlIlI5PfeCn1yOVjDS',
  'type': 'SequenceLocation',
  'digest': 'ZFKeEaewVWHpvfvlIlI5PfeCn1yOVjDS',
  'sequenceReference': {'type': 'SequenceReference',
   'refgetAccession': 'SQ.ItRDD47aMoioDCNW_occY5fWKZBKlxCX'},
  'start': [11211021, 11213338],
  'end': [11217364, 11218067]},
 'copyChange': 'gain'}

Note the coordinate shift: HGVS uses 1-based inclusive coordinates, VRS uses 0-based interbase. For the outer-left side, each boundary becomes N - 1; for the outer-right side, the boundaries are preserved. So (11211022_11213339) on the start side becomes [11211021, 11213338].

Example 2 — Left side unknown (?)

ClinVar variation 425669:

NC_000002.12:g.(?_202376935)_(202377551_202464808)del

The ? on the left indicates the outer-left breakpoint is completely unknown; the inner bound is 202376935. This becomes a Range with None as the lower bound: [None, 202376934].

In [3]
cnc = cnv_tlr.to_vrs(
    "NC_000002.12:g.(?_202376935)_(202377551_202464808)del", "hgvs"
)
cnc.model_dump(exclude_none=True)

Output:

{'id': 'ga4gh:CX.BazsTr3EQi7sWmQcG0k9Pa2p9IMi-mDu',
 'type': 'CopyNumberChange',
 'digest': 'BazsTr3EQi7sWmQcG0k9Pa2p9IMi-mDu',
 'location': {'id': 'ga4gh:SL.fs4VrXLo-EoFBXN32RS7yMwHPaUeqpIz',
  'type': 'SequenceLocation',
  'digest': 'fs4VrXLo-EoFBXN32RS7yMwHPaUeqpIz',
  'sequenceReference': {'type': 'SequenceReference',
   'refgetAccession': 'SQ.pnAqCRBrTsUoBghSD1yp_jXWSmlbdh4g'},
  'start': [None, 202376934],
  'end': [202377551, 202464808]},
 'copyChange': 'loss'}

Example 3 — Both sides unknown (?_X and X_?)

ClinVar variation 220591:

NC_000017.11:g.(?_58709859)_(58734342_?)del

Both outer bounds are unknown — producing [None, X] on the start and [X, None] on the end.

In [4]
cnc = cnv_tlr.to_vrs(
    "NC_000017.11:g.(?_58709859)_(58734342_?)del", "hgvs"
)
cnc.model_dump(exclude_none=True)

Output:

{'id': 'ga4gh:CX.KzAPXUkzFNk5KUOb8RyjdoPFZ8DCkfBt',
 'type': 'CopyNumberChange',
 'digest': 'KzAPXUkzFNk5KUOb8RyjdoPFZ8DCkfBt',
 'location': {'id': 'ga4gh:SL.WLMVDKSlxtyE9Py_t27VFaLrc8Uoqkme',
  'type': 'SequenceLocation',
  'digest': 'WLMVDKSlxtyE9Py_t27VFaLrc8Uoqkme',
  'sequenceReference': {'type': 'SequenceReference',
   'refgetAccession': 'SQ.dLZ15tNO1Ur0IcGjwc3Sdi_0A6Yf4zm7'},
  'start': [None, 58709858],
  'end': [58734342, None]},
 'copyChange': 'loss'}

Example 4 — CopyNumberCount with an uncertain range

Passing copies= produces a CopyNumberCount instead of a CopyNumberChange. The uncertain range is preserved exactly the same way.

In [5]
cn = cnv_tlr.to_vrs(
    "NC_000019.9:g.(11211022_11213339)_(11217364_11218067)dup",
    "hgvs",
    copies=3,
)
cn.model_dump(exclude_none=True)

Output:

{'id': 'ga4gh:CN._7pekRSZfY5XmqFXlOWmZ7XIWHG4ws03',
 'type': 'CopyNumberCount',
 'digest': '_7pekRSZfY5XmqFXlOWmZ7XIWHG4ws03',
 'location': {'id': 'ga4gh:SL.ZFKeEaewVWHpvfvlIlI5PfeCn1yOVjDS',
  'type': 'SequenceLocation',
  'digest': 'ZFKeEaewVWHpvfvlIlI5PfeCn1yOVjDS',
  'sequenceReference': {'type': 'SequenceReference',
   'refgetAccession': 'SQ.ItRDD47aMoioDCNW_occY5fWKZBKlxCX'},
  'start': [11211021, 11213338],
  'end': [11217364, 11218067]},
 'copies': 3}

Example 5 — VRS → HGVS (round-trip)

A VRS Allele whose SequenceLocation has Range bounds can be serialized back to uncertain-range HGVS via AlleleTranslator.from_vrs. Here we build the Allele directly (since from_hgvs on the Allele path refuses uncertain ranges) and confirm it round-trips.

In [6]
allele = models.Allele(
    location=models.SequenceLocation(
        sequenceReference=models.SequenceReference(
            refgetAccession="SQ.pnAqCRBrTsUoBghSD1yp_jXWSmlbdh4g"  # NC_000002.12
        ),
        start=models.Range(root=[None, 202376934]),
        end=models.Range(root=[202377551, 202464808]),
    ),
    state=models.LiteralSequenceExpression(sequence=models.sequenceString(root="")),
)
allele_tlr.from_vrs(allele, "hgvs")

Output:

['NC_000002.12:g.(?_202376935)_(202377551_202464808)del']

Example 6 — Why not AlleleTranslator.from_hgvs for uncertain ranges?

An Allele carries a concrete LiteralSequenceExpression (or similar) state. When breakpoints are uncertain, the reference sequence at the variant boundaries is unknown, so a literal sequence state is ill-defined. The translator raises a clear error and points you to CnvTranslator.

In [7]
try:
    allele_tlr.to_vrs(
        "NC_000019.9:g.(11211022_11213339)_(11217364_11218067)dup", "hgvs"
    )
except ValueError as err:
    print(type(err).__name__, ":", err)

Output:

ValueError : Uncertain-range HGVS expressions are not supported for Allele translation; use CnvTranslator for del/dup

Further reading

  • VRS-Python issue #609 — the work that enabled uncertain-range HGVS translation.
  • HGVS library issue #225 — full list of ClinVar test expressions covering del/dup with balanced, left-?, right-?, and both-? forms.
  • VRS 2.x spec section on SequenceLocation — documents how Range values are used for the start / end fields.