Skip to content

Translation and HGVS

Translates various external formats into VRS models.

Input formats: VRS (serialized), hgvs, spdi, gnomad (vcf) Output formats: hgvs and spdi for Alleles; no copy-number exporters.

USE_INSTANCE_DEFAULT module-attribute

USE_INSTANCE_DEFAULT = TranslationDefault.INSTANCE

Use the translator instance setting for an omitted option.

TranslationDefault

Bases: Enum

Mark options that use the translator instance setting.

USE_INSTANCE_DEFAULT distinguishes an omitted option from an explicit None. For rle_seq_limit, the default uses the instance limit, while None means no limit. Enum members preserve their identity through copying and pickling.

VariationToStrProtocol

Bases: Protocol

Protocol for translating VRS objects to other string expressions.

This protocol defines a callable interface for translating a VRS object into variation strings, with optional keyword arguments for customization.

__call__

__call__(vo: _VariationBase, **kwargs: object) -> list[str]

Translate vrs object vo to variation string expressions

Parameters:

Name Type Description Default
vo _VariationBase

VRS object to translate.

required
kwargs object

Additional options passed to the implementation.

{}

Returns:

Type Description
list[str]

Translated expressions.

VariationFromStrProtocol

Bases: Protocol

Protocol for translating variation strings to VRS objects.

This protocol defines a callable interface for translating a variation string into a VRS object, with optional keyword arguments for customization.

__call__

__call__(
    expr: str | dict, **kwargs: object
) -> _VariationBase | None

Translate variation string expr to a VRS object

Parameters:

Name Type Description Default
expr str | dict

Variation expression or VRS dictionary for the selected parser.

required
kwargs object

Additional options passed to the implementation.

{}

Returns:

Type Description
_VariationBase | None

Translated VRS object, or None if unsupported.

AlleleTranslator

AlleleTranslator(
    data_proxy: _DataProxy,
    default_assembly_name: str = "GRCh38",
    identify: bool = True,
)

Bases: _Translator

Class for translating formats to and from VRS Alleles

Initialize translation to and from VRS Alleles.

Parameters:

Name Type Description Default
data_proxy _DataProxy

Sequence data provider used during translation.

required
default_assembly_name str

Default assembly for gnomAD inputs.

'GRCh38'
identify bool

Whether to assign GA4GH identifiers to translated objects.

True

from_gnomad

from_gnomad(
    gnomad_expr: str,
    *,
    assembly_name: str | None = None,
    require_validation: bool = True,
    do_normalize: bool = True,
    rle_seq_limit: int
    | None
    | TranslationDefault = USE_INSTANCE_DEFAULT,
    **kwargs: object,
) -> Allele | None

Parse gnomAD-style VCF expression into VRS Allele

Parameters:

Name Type Description Default
gnomad_expr str

Variant in chr-pos-ref-alt format.

required
assembly_name str | None

Assembly used for the input, or None for the instance default.

None
require_validation bool

Whether reference mismatches raise an error (default True).

True
do_normalize bool

Whether to perform fully justified normalization (default True).

True
rle_seq_limit int | None | TranslationDefault

Maximum RLE sequence length to include. USE_INSTANCE_DEFAULT uses the instance limit; 0 excludes the sequence and None includes it without a limit.

USE_INSTANCE_DEFAULT
kwargs object

Unused options accepted for format dispatch.

{}

Returns:

Type Description
Allele | None

Translated Allele, or None if the expression or accession is unrecognized.

Raises:

Type Description
DataProxyValidationError

If reference validation is required and fails, or the location is outside the reference sequence.

With tlr configured for the reference sequence, disable normalization to inspect the input coordinates and alternate sequence:

>>> a = tlr.from_gnomad("1-55516888-G-GA", do_normalize=False)
>>> a.location.start, a.location.end
(55516887, 55516888)
>>> a.state.sequence.root
'GA'

from_hgvs

from_hgvs(
    hgvs_expr: str,
    *,
    do_normalize: bool = True,
    rle_seq_limit: int
    | None
    | TranslationDefault = USE_INSTANCE_DEFAULT,
    **kwargs: object,
) -> Allele | None

Parse an HGVS expression into a VRS Allele.

Parameters:

Name Type Description Default
hgvs_expr str

HGVS variant expression.

required
do_normalize bool

Whether to perform fully justified normalization (default True).

True
rle_seq_limit int | None | TranslationDefault

Maximum RLE sequence length to include. USE_INSTANCE_DEFAULT uses the instance limit; 0 excludes the sequence and None includes it without a limit.

USE_INSTANCE_DEFAULT
kwargs object

Unused options accepted for format dispatch.

{}

Returns:

Type Description
Allele | None

Translated Allele, or None if the expression or accession is unrecognized.

Raises:

Type Description
ValueError

If HGVS positions or edits cannot be represented as an Allele.

DataProxyValidationError

If the location is outside the reference sequence.

from_spdi

from_spdi(
    spdi_expr: str,
    *,
    do_normalize: bool = True,
    rle_seq_limit: int
    | None
    | TranslationDefault = USE_INSTANCE_DEFAULT,
    **kwargs: object,
) -> Allele | None

Parse SPDI expression in to a GA4GH Allele

Parameters:

Name Type Description Default
spdi_expr str

Variant in accession:position:deletion:insertion format.

required
do_normalize bool

Whether to perform fully justified normalization (default True).

True
rle_seq_limit int | None | TranslationDefault

Maximum RLE sequence length to include. USE_INSTANCE_DEFAULT uses the instance limit; 0 excludes the sequence and None includes it without a limit.

USE_INSTANCE_DEFAULT
kwargs object

Unused options accepted for format dispatch.

{}

Returns:

Type Description
Allele | None

Translated Allele, or None if the expression or accession is unrecognized.

Raises:

Type Description
DataProxyValidationError

If the location is outside the reference sequence.

With tlr configured for the reference sequence, disable normalization to inspect the input coordinates and alternate sequence:

>>> a = tlr.from_spdi("NC_000013.11:32936731:1:C", do_normalize=False)
>>> a.location.start, a.location.end
(32936731, 32936732)
>>> a.state.sequence.root
'C'

to_hgvs

to_hgvs(
    vo: Allele,
    namespace: str | None = "refseq",
    **kwargs: object,
) -> list[str]

Generate HGVS expressions for a VRS Allele.

Parameters:

Name Type Description Default
vo Allele

Allele to translate.

required
namespace str | None

Sequence identifier namespace, or None for all aliases.

'refseq'
kwargs object

Unused options accepted for format dispatch.

{}

Returns:

Type Description
list[str]

HGVS expressions, or an empty list if no aliases are available.

Raises:

Type Description
ValueError

If the object cannot be represented as HGVS.

to_spdi

to_spdi(
    vo: Allele,
    namespace: str | None = "refseq",
    *,
    ref_seq_limit: int | None = 0,
    **kwargs: object,
) -> list[str]

Generate a list of SPDI expressions for VRS Allele.

If namespace is not None, returns SPDI strings for the specified namespace.

If namespace is None, returns SPDI strings for all alias translations.

If ref_seq_limit is specified, the reference sequence is included in the SPDI expression only if its length is at most the limit. Otherwise only the length of the reference sequence is included. If the limit is None, the reference sequence is always included. In all cases, the alt sequence is included. Default is 0 (never include reference sequence).

If no alias translations are available, an empty list is returned.

Requires an inline SequenceLocation with integer bounds and either a LiteralSequenceExpression or a ReferenceLengthExpression with integer length and a positive repeatSubunitLength. Unsupported model shapes are not validated before their fields are accessed.

SPDI and VRS use identical normalization. The incoming Allele is expected to be normalized per VRS spec.

Parameters:

Name Type Description Default
vo Allele

Allele to translate.

required
namespace str | None

Sequence identifier namespace, or None for all aliases.

'refseq'
ref_seq_limit int | None

Maximum reference sequence length to include (default 0). None always includes the reference sequence.

0
kwargs object

Unused options accepted for format dispatch.

{}

Returns:

Type Description
list[str]

SPDI expressions, or an empty list if no aliases are available.

Raises:

Type Description
ValueError

If a reference repeat subunit cannot be reconstructed.

to_vrs

to_vrs(
    var: str | dict,
    fmt: str | None = None,
    **kwargs: object,
) -> _VariationBase

Translate a variation expression or VRS JSON dictionary to a VRS object.

If fmt is omitted, try the registered parsers in order. Format-specific methods return None for unrecognized input; this method raises ValueError.

Parameters:

Name Type Description Default
var str | dict

Variation expression, or a VRS JSON dictionary with fmt="vrs".

required
fmt str | None

Input format, or None to try the registered parsers.

None
kwargs object

Options forwarded to the selected parser. Unused options are ignored.

For AlleleTranslator HGVS, SPDI, and gnomAD inputs:

  • do_normalize (bool): Whether to perform fully justified normalization. Defaults to True.
  • rle_seq_limit (int or None): Maximum sequence length to include when normalization produces a ReferenceLengthExpression. Omission or USE_INSTANCE_DEFAULT uses the instance's rle_seq_limit. Set to 0 to exclude the sequence, or None for no limit.

Additional options for AlleleTranslator gnomAD inputs:

  • assembly_name (str or None): Assembly used for the input. Omission or None uses the instance's default_assembly_name.
  • require_validation (bool): Whether reference mismatches raise DataProxyValidationError. Defaults to True. False allows reference mismatches; location bounds are still validated.

For CnvTranslator HGVS inputs:

  • copies (int, models.Range, or None): Copy count or range, including zero. If supplied, returns CopyNumberCount and takes precedence over copy_change. Defaults to None.
  • copy_change (models.CopyChange or None): Copy change used when copies is omitted or None. Defaults to CopyChange.LOSS ("loss") for deletions and CopyChange.GAIN ("gain") for duplications.
{}

Returns:

Type Description
_VariationBase

Translated VRS variation.

Raises:

Type Description
NotImplementedError

If the requested format is unsupported.

ValueError

If the input cannot be parsed or represented.

DataProxyValidationError

If required reference or location validation fails.

from_vrs

from_vrs(
    vo: _VariationBase, fmt: str, **kwargs: object
) -> list[str]

Translate a VRS object to expressions in the requested format.

Parameters:

Name Type Description Default
vo _VariationBase

VRS variation to translate.

required
fmt str

Output format.

required
kwargs object

Options forwarded to the selected exporter. Unused options are ignored.

For AlleleTranslator HGVS and SPDI exports:

  • namespace (str or None): Sequence identifier namespace. Defaults to "refseq". None includes all available aliases.

Additional options for AlleleTranslator SPDI exports:

  • ref_seq_limit (int or None): Maximum reference sequence length to include in the SPDI expression. Longer reference sequences are represented by their length. Defaults to 0; None always includes the reference sequence. The alternate sequence is always included, including when derived from a ReferenceLengthExpression.
{}

Returns:

Type Description
list[str]

Expressions in the requested format.

Raises:

Type Description
NotImplementedError

If the requested format is unsupported.

ValueError

If the object cannot be represented in the requested format.

from_vrs_dict

from_vrs_dict(
    var: object, **kwargs: object
) -> _VariationBase | None

Parse a VRS JSON dictionary into a VRS variation object.

Parameters:

Name Type Description Default
var object

Dictionary containing a VRS variation and its type.

required
kwargs object

Unused options accepted for format dispatch.

{}

Returns:

Type Description
_VariationBase | None

Parsed variation, or None for non-mappings or missing type.

Raises:

Type Description
pydantic.ValidationError

If the dictionary is not a valid variation.

hgvs_tools

hgvs_tools() -> HgvsTools

Instantiate and return an HgvsTools instance

Returns:

Type Description
HgvsTools

Lazily initialized HGVS tools.

CnvTranslator

CnvTranslator(
    data_proxy: _DataProxy,
    default_assembly_name: str = "GRCh38",
    identify: bool = True,
)

Bases: _Translator

Class for translating formats from format to VRS Copy Number

Initialize translation from HGVS to VRS copy number objects.

Parameters:

Name Type Description Default
data_proxy _DataProxy

Sequence data provider used during translation.

required
default_assembly_name str

Default assembly name.

'GRCh38'
identify bool

Whether to assign GA4GH identifiers to translated objects.

True

from_hgvs

from_hgvs(
    hgvs_dup_del_expr: str,
    *,
    copies: int | Range | None = None,
    copy_change: CopyChange | None = None,
    **kwargs: object,
) -> CopyNumberChange | CopyNumberCount | None

Parse an HGVS deletion or duplication into a VRS copy number object.

Parameters:

Name Type Description Default
hgvs_dup_del_expr str

HGVS deletion or duplication expression.

required
copies int | Range | None

Copy count or range, including zero. If supplied, returns CopyNumberCount and takes precedence over copy_change.

None
copy_change CopyChange | None

Copy change, defaulting to LOSS for deletions and GAIN for duplications when copies is omitted.

None
kwargs object

Unused options accepted for format dispatch.

{}

Returns:

Type Description
CopyNumberChange | CopyNumberCount | None

CopyNumberCount if copies is supplied, otherwise CopyNumberChange, or None if the expression or accession is unrecognized.

Raises:

Type Description
ValueError

If the edit is not a deletion or duplication, or its positions cannot be represented as a copy number location.

DataProxyValidationError

If the location is outside the reference sequence.

to_vrs

to_vrs(
    var: str | dict,
    fmt: str | None = None,
    **kwargs: object,
) -> _VariationBase

Translate a variation expression or VRS JSON dictionary to a VRS object.

If fmt is omitted, try the registered parsers in order. Format-specific methods return None for unrecognized input; this method raises ValueError.

Parameters:

Name Type Description Default
var str | dict

Variation expression, or a VRS JSON dictionary with fmt="vrs".

required
fmt str | None

Input format, or None to try the registered parsers.

None
kwargs object

Options forwarded to the selected parser. Unused options are ignored.

For AlleleTranslator HGVS, SPDI, and gnomAD inputs:

  • do_normalize (bool): Whether to perform fully justified normalization. Defaults to True.
  • rle_seq_limit (int or None): Maximum sequence length to include when normalization produces a ReferenceLengthExpression. Omission or USE_INSTANCE_DEFAULT uses the instance's rle_seq_limit. Set to 0 to exclude the sequence, or None for no limit.

Additional options for AlleleTranslator gnomAD inputs:

  • assembly_name (str or None): Assembly used for the input. Omission or None uses the instance's default_assembly_name.
  • require_validation (bool): Whether reference mismatches raise DataProxyValidationError. Defaults to True. False allows reference mismatches; location bounds are still validated.

For CnvTranslator HGVS inputs:

  • copies (int, models.Range, or None): Copy count or range, including zero. If supplied, returns CopyNumberCount and takes precedence over copy_change. Defaults to None.
  • copy_change (models.CopyChange or None): Copy change used when copies is omitted or None. Defaults to CopyChange.LOSS ("loss") for deletions and CopyChange.GAIN ("gain") for duplications.
{}

Returns:

Type Description
_VariationBase

Translated VRS variation.

Raises:

Type Description
NotImplementedError

If the requested format is unsupported.

ValueError

If the input cannot be parsed or represented.

DataProxyValidationError

If required reference or location validation fails.

from_vrs

from_vrs(
    vo: _VariationBase, fmt: str, **kwargs: object
) -> list[str]

Translate a VRS object to expressions in the requested format.

Parameters:

Name Type Description Default
vo _VariationBase

VRS variation to translate.

required
fmt str

Output format.

required
kwargs object

Options forwarded to the selected exporter. Unused options are ignored.

For AlleleTranslator HGVS and SPDI exports:

  • namespace (str or None): Sequence identifier namespace. Defaults to "refseq". None includes all available aliases.

Additional options for AlleleTranslator SPDI exports:

  • ref_seq_limit (int or None): Maximum reference sequence length to include in the SPDI expression. Longer reference sequences are represented by their length. Defaults to 0; None always includes the reference sequence. The alternate sequence is always included, including when derived from a ReferenceLengthExpression.
{}

Returns:

Type Description
list[str]

Expressions in the requested format.

Raises:

Type Description
NotImplementedError

If the requested format is unsupported.

ValueError

If the object cannot be represented in the requested format.

from_vrs_dict

from_vrs_dict(
    var: object, **kwargs: object
) -> _VariationBase | None

Parse a VRS JSON dictionary into a VRS variation object.

Parameters:

Name Type Description Default
var object

Dictionary containing a VRS variation and its type.

required
kwargs object

Unused options accepted for format dispatch.

{}

Returns:

Type Description
_VariationBase | None

Parsed variation, or None for non-mappings or missing type.

Raises:

Type Description
pydantic.ValidationError

If the dictionary is not a valid variation.

hgvs_tools

hgvs_tools() -> HgvsTools

Instantiate and return an HgvsTools instance

Returns:

Type Description
HgvsTools

Lazily initialized HGVS tools.

Convert HGVS expressions and coordinates.

HGVS uses 1-based positions; VRS uses interbase bounds. Omitting the accession::

HGVS                            VRS start        VRS end
g.100A>T                        99               100
g.100_101insT                    100              100
g.(100_110)_(200_210)del          Range([99,109])  Range([200,210])

Insertions use the boundary after the start residue for both bounds. For ranges, starts shift by one and ends stay unchanged. AlleleTranslator rejects uncertain ranges; use CnvTranslator for uncertain del/dup copy-number expressions.

With a configured data_proxy and accessible UTA database::

from ga4gh.vrs.extras.translator import AlleleTranslator

translator = AlleleTranslator(data_proxy)
try:
    allele = translator.from_hgvs("NC_000019.10:g.44908822C>T")
    expressions = translator.to_hgvs(allele, namespace="refseq")
finally:
    translator.hgvs_tools.close()  # Closes UTA, not the supplied data proxy.

Coding coordinates pass through c_to_n on import and n_to_c on export.

HgvsTools

HgvsTools(data_proxy: _DataProxy | None = None)

Provide tools for working with HGVS notation.

Use a context manager or call close() to close this instance's UTA connection. The caller owns the supplied data proxy, which stays open.

Attributes: parser (hgvs.parser.Parser): The HGVS parser object. uta_conn: The UTA (Universal Transcript Archive) connection object. normalizer: The HGVS normalizer object. variant_mapper: The HGVS variant mapper object. data_proxy (_DataProxy): The data proxy object.

Create the HGVS parser, normalizer, variant mapper, and UTA connection.

Close the UTA connection if normalizer or variant mapper setup fails. If cleanup also fails, raise its error with the setup error chained.

Parameters:

Name Type Description Default
data_proxy _DataProxy | None

Optional caller-owned GA4GH data proxy.

None

close

close() -> None

Close this instance's UTA connection.

Repeated calls after success do nothing. Cleanup errors propagate; callers can retry. Keep all resource references and leave the supplied data proxy open. Operations that need UTA are unsupported after closure.

__enter__

__enter__() -> Self

Return this instance for use in a context manager.

Returns:

Type Description
Self

This instance.

Raises:

Type Description
RuntimeError

If already closed.

__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) -> None

Close the owned UTA connection without suppressing exceptions.

If cleanup fails, raise its error with any context body error chained.

Parameters:

Name Type Description Default
exc_type type[BaseException] | None

Exception type from the context body, if any.

required
exc_value BaseException | None

Exception from the context body, if any.

required
traceback TracebackType | None

Traceback from the context body, if any.

required

parse

parse(hgvs_str: str) -> SequenceVariant | None

Parse the given HGVS string and returns the corresponding variant.

Parameters:

Name Type Description Default
hgvs_str str

HGVS expression to parse.

required

Returns:

Type Description
SequenceVariant | None

Parsed variant, or None if the expression prefix is unsupported.

Raises:

Type Description
hgvs.exceptions.HGVSParseError

If a supported expression has invalid syntax.

has_uncertain_range

has_uncertain_range(sv: SequenceVariant) -> bool

Check whether either variant endpoint is an uncertain interval.

For example, the endpoints in (A_B)_(C_D)del are nested uncertain intervals.

Parameters:

Name Type Description Default
sv SequenceVariant

Parsed HGVS sequence variant.

required

Returns:

Type Description
bool

Whether either endpoint is an uncertain range.

is_intronic

is_intronic(sv: SequenceVariant) -> bool

Check if the given SequenceVariant is intronic.

Parameters:

Name Type Description Default
sv SequenceVariant

Parsed HGVS sequence variant.

required

Returns:

Type Description
bool

Whether either endpoint is intronic.

get_edit_type

get_edit_type(sv: SequenceVariant | None) -> str | None

Safely extract type property from SequenceVariant

Parameters:

Name Type Description Default
sv SequenceVariant | None

Parsed HGVS sequence variant.

required

Returns:

Type Description
str | None

Edit type, or None if no edit is present.

get_position_and_state

get_position_and_state(
    sv: SequenceVariant,
) -> tuple[_VrsPos, _VrsPos, str]

Get the details of a sequence variant.

Parameters:

Name Type Description Default
sv SequenceVariant

Parsed HGVS sequence variant.

required

Returns:

Type Description
tuple[_VrsPos, _VrsPos, str]

VRS start, end, and literal alternate sequence.

Raises:

Type Description
ValueError

If the edit type or an intronic position is unsupported.

TypeError

If a transcript range cannot be represented in VRS.

AttributeError

If an operation needing sequence data is called without a data proxy.

extract_allele_values

extract_allele_values(hgvs_expr: str) -> dict | None

Extract allele construction fields from an HGVS expression.

Parameters:

Name Type Description Default
hgvs_expr str

HGVS expression to translate.

required

Returns:

Type Description
dict | None

Allele fields, or None for an unsupported expression prefix or unresolved accession. Invalid HGVS syntax raises HGVSParseError.

Raises:

Type Description
ValueError

If the variant is intronic or its edit type is unsupported.

AttributeError

If an operation needing sequence data is called without a data proxy.

TypeError

If a transcript range cannot be represented in VRS.

hgvs.exceptions.HGVSParseError

If supported HGVS syntax is malformed.

build_cnv_location

build_cnv_location(
    sv: SequenceVariant, refget_accession: str
) -> SequenceLocation

Build a VRS :class:SequenceLocation from a parsed hgvs CNV variant.

CDS-relative (c.) inputs are translated to transcript-relative (n.) coordinates first; without that step the VRS location would point into the 5' UTR. Handles both certain positions and uncertain- range endpoints; the resulting start / end are ints for exact positions and :class:models.Range values for uncertain ranges.

Parameters:

Name Type Description Default
sv SequenceVariant

Parsed HGVS sequence variant.

required
refget_accession str

Refget accession for the location sequence.

required

Returns:

Type Description
SequenceLocation

Sequence location with translated coordinates.

Raises:

Type Description
TypeError

If a transcript range cannot be represented in VRS.

ValueError

If a position is intronic or an exact interval has unequal endpoints.

from_allele

from_allele(
    vo: Allele | None, namespace: str | None = None
) -> list[str]

Generate a list of HGVS expressions for VRS Allele.

If namespace is not None, returns HGVS strings for the specified namespace.

If namespace is None, returns HGVS strings for all alias translations.

If no alias translations are available, an empty list is returned.

If the VRS object cannot be expressed as HGVS, raises ValueError.

Parameters:

Name Type Description Default
vo Allele | None

VRS object to translate.

required
namespace str | None

Optional namespace used to filter sequence aliases.

None

Returns:

Type Description
list[str]

Distinct HGVS expressions for supported matching aliases, or an empty list for None. Protein accessions raise ValueError.

Raises:

Type Description
ValueError

If the allele or sequence reference cannot be represented.

AttributeError

If an operation needing sequence data is called without a data proxy.

normalize

normalize(hgvs: SequenceVariant) -> SequenceVariant

Perform hgvs library normalize() method

Parameters:

Name Type Description Default
hgvs SequenceVariant

HGVS variant to normalize or map.

required

Returns:

Type Description
SequenceVariant

Normalized HGVS variant.

Raises:

Type Description
hgvs.exceptions.HGVSError

If the HGVS operation fails validation or required data is unavailable.

n_to_c

n_to_c(hgvs: SequenceVariant) -> SequenceVariant

Perform hgvs library n_to_c method

Parameters:

Name Type Description Default
hgvs SequenceVariant

HGVS variant to normalize or map.

required

Returns:

Type Description
SequenceVariant

Variant in coding coordinates.

Raises:

Type Description
hgvs.exceptions.HGVSError

If the HGVS operation fails validation or required data is unavailable.

c_to_n

c_to_n(hgvs: SequenceVariant) -> SequenceVariant

Perform hgvs library c_to_n method

Parameters:

Name Type Description Default
hgvs SequenceVariant

HGVS variant to normalize or map.

required

Returns:

Type Description
SequenceVariant

Variant in transcript coordinates.

Raises:

Type Description
hgvs.exceptions.HGVSError

If the HGVS operation fails validation or required data is unavailable.