Skip to content

Normalization

Normalize alleles before computing identifiers so equivalent indel descriptions produce consistent results. Normalization requires sequence data.

Normalize VRS objects.

Allele normalization validates bounds, trims shared sequence, expands repeat ambiguity, and chooses a literal or reference-length expression. Substitutions and identity alleles return before expansion.

For reference CAAAG, inserting A inside the run expands as follows::

input:    [2, 2), literal "A"
expanded: [1, 4), reference "AAA", alternate "AAAA"
output:   ReferenceLengthExpression(length=4, repeatSubunitLength=1)

A substitution needs only trimming: ACGT -> ATGT at [0, 4) becomes C -> T at [1, 2), with a LiteralSequenceExpression.

Given an inline literal Allele and a data proxy serving its reference::

from ga4gh.vrs import normalize

compact = normalize(allele, data_proxy, rle_seq_limit=0)
with_sequence = normalize(allele, data_proxy, rle_seq_limit=None)

0 omits the optional RLE sequence; None retains it without a length limit. A positive limit retains the complete sequence only if it fits. Use the original literal input for each call: existing RLE states are returned unchanged.

See https://vrs.ga4gh.org/en/stable/impl-guide/normalization.html

PosType

Bases: IntEnum

Define the kind of position on a location

LocationPos

Bases: NamedTuple

Define Allele location pos value and type

denormalize_reference_length_expression

denormalize_reference_length_expression(
    ref_seq: str,
    repeat_subunit_length: int,
    alt_length: int,
) -> str

Expand a ReferenceLengthExpression into its alternate sequence.

Repeat the reference subunit to alt_length characters, including a trailing partial copy when needed.

e.g. "ACGT" (repeat_subunit_length=4, length=10) -> "ACGTACGTAC" (ACGT ACGT AC)

Parameters:

Name Type Description Default
ref_seq str

The reference sequence to be denormalized.

required
repeat_subunit_length int

The length of the repeat subunit.

required
alt_length int

The length of the alternate sequence that was compacted during normalization.

required

Returns:

Type Description
str

Expanded alternate sequence.

Raises:

Type Description
ValueError

If the subunit length is negative or exceeds the reference length.

ZeroDivisionError

If the repeat subunit length is zero.

normalize

normalize(
    vo: BaseModel,
    data_proxy: _DataProxy | None = None,
    **kwargs: int | None,
) -> BaseModel

Normalize given vrs object, regardless of type

Parameters:

Name Type Description Default
vo BaseModel

VRS object to normalize.

required
kwargs int | None

Allele handler options. rle_seq_limit limits retained RLE sequence length; 0 omits it and None removes the limit. CisPhasedBlock accepts no extra options.

{}
data_proxy _DataProxy | None

Required for supported Allele normalization; unused by CisPhasedBlock normalization.

None

Returns:

Type Description
BaseModel

Normalized object of the input type. Alleles may be copied; CisPhasedBlock members are sorted in place. Unsupported types are returned unchanged. The input must expose a VRS type attribute.

Raises:

Type Description
TypeError

if given object isn't a pydantic.BaseModel