Notebook source
Rendered from notebooks/getting_started/7_Uncertain_Range_HGVS.ipynb.
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.
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:
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.
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:
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].
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:
Both outer bounds are unknown — producing [None, X] on the start and [X, None] on the end.
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.
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.
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:
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.
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/dupwith balanced, left-?, right-?, and both-?forms. - VRS 2.x spec section on SequenceLocation — documents how
Rangevalues are used for thestart/endfields.