diff --git a/docs/source/concepts/MolecularVariation/RelativeAllele.rst b/docs/source/concepts/MolecularVariation/RelativeAllele.rst index 5c80d554..cb6e7a29 100644 --- a/docs/source/concepts/MolecularVariation/RelativeAllele.rst +++ b/docs/source/concepts/MolecularVariation/RelativeAllele.rst @@ -7,3 +7,55 @@ Definition and Information Model @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ .. include:: ../../def/vrs/RelativeAllele.rst + +Example +@@@@@@@ + +There are several :ref:`splice-adjacent-examples` with more details. +Below is an example of a splice acceptor downstream relative allele. + +.. code-block:: json + + { + "type": "RelativeAllele", + "relativeLocation": { + "baseSequenceLocation": { + "type": "SequenceLocation", + "sequenceReference": { + "type": "SequenceReference", + "id": "NC_000010.11", + "refgetAccession": "SQ.ss8r_wB0-b9r44TQTMmVTI92884QvBiB" + }, + "start": 95387120, + "end": 95387121 + }, + "mappedSequenceLocation": { + "sequenceReference": { + "type": "SequenceReference", + "id": "NM_001034954.3", + "refgetAccession": "SQ.SDt4gIJa8ChOmuI3te-3gpbJExmt1dHX" + }, + "anchor": 1543, + "anchorOrientation": "right", + "offsetStart": -2837, + "offsetEnd": -2836 + } + }, + "mappedState": { + "type": "LiteralSequenceExpression", + "sequence": "G" + }, + "baseState": { + "type": "LiteralSequenceExpression", + "sequence": "C" + } + } + +Implementation Guidance +@@@@@@@@@@@@@@@@@@@@@@@ + +Normalization +############# + +The ``RelativeAllele`` also includes conventions for variant normalization (see :ref:`relative-allele-normalization`) that allows for compact and +uniform representation of relative allele variants. diff --git a/docs/source/conventions/normalization.rst b/docs/source/conventions/normalization.rst index 170a8af2..bb496c8d 100644 --- a/docs/source/conventions/normalization.rst +++ b/docs/source/conventions/normalization.rst @@ -225,3 +225,67 @@ is definitional and must be specified using a :ref:`TraversalBlock`. depending on orientation.** In the top example, a 100-base sequence is deleted and replaced by a 1000-base inverted sequence. In the bottom example, a 100-base inverted sequence is inserted, and a 1000-base sequence is duplicated. + + + +.. _relative-allele-normalization: + +Relative Allele Normalization +@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +.. admonition:: New in v2.1 + + The relativeAllele class was added in v2.1 to describe alleles relative to a mapped sequence + from a base sequence alignment. + +:ref:`RelativeAllele` normalization differs fundamentally from Allele normalization. Allele normalization +applies fully-justified expansion to resolve positional ambiguity for indels on a single reference +sequence. In contrast, a RelativeAllele's location is anchored to a specific alignment boundary +between two sequences. The anchor and offsets are structurally constrained by the transcript-to-genome +mapping and are not subject to the same kind of positional ambiguity that fully-justified normalization +addresses. + +Therefore, Allele-style fully-justified normalization MUST NOT be applied to a :ref:`RelativeAllele` — +doing so could shift the `baseSequenceLocation` away from the position that corresponds to the `anchor + offset` +mapping, breaking the semantic relationship between the two sequences. + +When normalizing a :ref:`RelativeAllele`, the following rules apply: + +0. **Preconditions.** Start with an unnormalized RelativeAllele containing a `relativeLocation` + (with `baseSequenceLocation` and `mappedSequenceLocation`), a `baseState`, and a `mappedState`. + +#. **Normalize nested identifiable objects.** All nested identifiable objects (e.g., SequenceLocation, + SequenceReference) MUST be expressed using GA4GH Computed Identifiers, consistent with the general + VRS computed identifier requirements. + +#. **Normalize the baseSequenceLocation as a SequenceLocation.** The `baseSequenceLocation` is a standard + VRS SequenceLocation and MUST be normalized according to SequenceLocation normalization rules + (e.g., ensuring refgetAccession is used). However, its `start` and `end` coordinates MUST NOT be altered + by Allele-style fully-justified expansion — they represent the resolved genomic position derived from + the anchor + offset mapping. + +#. **Validate state consistency.** The `baseState` and `mappedState` MUST be consistent with each other given + the strand orientation implied by the transcript-to-genome alignment. Specifically: + + * If the mapped sequence is on the positive strand relative to the base sequence, `baseState` and `mappedState` + MUST be identical. + * If the mapped sequence is on the negative strand (reverse complement), `baseState` MUST be the reverse complement + of `mappedState`. + +If states are inconsistent, implementations SHOULD raise an error rather than silently correcting, since the +inconsistency may indicate a data entry error. + +4. **Validate offset consistency.** The interval defined by `offsetStart` and `offsetEnd` MUST satisfy `offsetEnd + - offsetStart` equal to `end - start` of the `baseSequenceLocation`. That is, the length of the interval on the + mapped sequence must equal the length of the interval on the base sequence. Implementations SHOULD raise an + error if this constraint is violated. + +#. **Return the normalized RelativeAllele.** Construct and return a new RelativeAllele with all nested objects + expressed using computed identifiers. + +**What is NOT normalized** + +* **Anchor position** (`anchor`): Definitional. Determined by the exon boundary in the transcript alignment. Not subject to adjustment. +* **Anchor orientation** (`anchorOrientation`): Definitional. Determined by splice context (left for donor, right for acceptor). +* **Offsets** (`offsetStart`, `offsetEnd`): Definitional. Determined by the HGVS offset from the exon boundary. +* **Base/mapped state sequences** : Not subject to trimming or expansion. The states represent the allele as expressed on their respective sequences and must remain paired. diff --git a/docs/source/examples/SpliceVariants/index.rst b/docs/source/examples/SpliceVariants/index.rst index 0973227f..da35aa75 100644 --- a/docs/source/examples/SpliceVariants/index.rst +++ b/docs/source/examples/SpliceVariants/index.rst @@ -1,3 +1,5 @@ +.. _splice-adjacent-examples: + Splice-Adjacent HGVS Variant Examples =====================================