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 |