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__
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__
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 |
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 |
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
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:
Additional options for AlleleTranslator gnomAD inputs:
For CnvTranslator HGVS inputs:
|
{}
|
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
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:
Additional options for AlleleTranslator SPDI exports:
|
{}
|
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
Parse a VRS JSON dictionary into a VRS variation object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
var
|
object
|
Dictionary containing a VRS variation and its |
required |
kwargs
|
object
|
Unused options accepted for format dispatch. |
{}
|
Returns:
| Type | Description |
|---|---|
_VariationBase | None
|
Parsed variation, or None for non-mappings or missing |
Raises:
| Type | Description |
|---|---|
pydantic.ValidationError
|
If the dictionary is not a valid variation. |
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 |
None
|
copy_change
|
CopyChange | None
|
Copy change, defaulting to LOSS for deletions and
GAIN for duplications when |
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
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:
Additional options for AlleleTranslator gnomAD inputs:
For CnvTranslator HGVS inputs:
|
{}
|
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
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:
Additional options for AlleleTranslator SPDI exports:
|
{}
|
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
Parse a VRS JSON dictionary into a VRS variation object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
var
|
object
|
Dictionary containing a VRS variation and its |
required |
kwargs
|
object
|
Unused options accepted for format dispatch. |
{}
|
Returns:
| Type | Description |
|---|---|
_VariationBase | None
|
Parsed variation, or None for non-mappings or missing |
Raises:
| Type | Description |
|---|---|
pydantic.ValidationError
|
If the dictionary is not a valid variation. |
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 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__
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 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
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
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
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 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 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
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
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
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. |