Refine components in TraversalBlock (#554)

* `Adjacency` is the only component in a `TraversalBlock` `Allele`, `CisPhasedBlock`, and `Terminus` can be specified directly on the `DerivativeMolecule` * Add adjacency orientation example --------- Co-authored-by: Alex H. Wagner, PhD <[email protected]>
ga4gh · Oct 23, 2024 · 52fd157 · 52fd157
1 parent f2ec1ba
commit 52fd157
Show file tree

Hide file tree

Showing 8 changed files with 59 additions and 58 deletions.
diff --git a/docs/source/conventions/normalization.rst b/docs/source/conventions/normalization.rst
@@ -215,3 +215,13 @@ will be selected by meeting the following ordered criteria.
 1. The first of the adjoined sequences MUST have a forward orientation (location defined by `end`).
 2. The adjoined sequence accessions are equal or in ascending lexicographical order.
 3. The defined adjoined sequence coordinates are in ascending numerical order.
+
+When adjacencies are used in the context of a :ref:`DerivativeMolecule`, the orientation
+is definitional and must be specified using a :ref:`TraversalBlock`.
+
+.. figure:: ../images/ex_adjacency_orientation.png
+
+   **The same pair of adjacencies can produce significantly different derivative molecules
+   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.
diff --git a/docs/source/images/ex_adjacency_orientation.png b/docs/source/images/ex_adjacency_orientation.png
diff --git a/examples/sv_derivative_molecule.yaml b/examples/sv_derivative_molecule.yaml
@@ -1,19 +1,16 @@
 id: sv_derivative_molecule
 type: DerivativeMolecule
 components:
-  - type: TraversalBlock
-    orientation: forward
-    component: 
-      id: 5-prime-terminus
-      type: Terminus
-      location:
-        type: SequenceLocation
-        sequenceReference:
-          type: SequenceReference
-          refgetAccession: SQ.S_KjnFVz-FE7M0W6yoaUDgYxLPc1jyWU
-          residueAlphabet: na
-          id: NC_000001.10
-        end: 123
+  - id: 5-prime-terminus
+    type: Terminus
+    location:
+      type: SequenceLocation
+      sequenceReference:
+        type: SequenceReference
+        refgetAccession: SQ.S_KjnFVz-FE7M0W6yoaUDgYxLPc1jyWU
+        residueAlphabet: na
+        id: NC_000001.10
+      end: 123
   - type: TraversalBlock
     orientation: forward
     component: 
@@ -37,22 +34,19 @@ components:
       linker: 
         type: LiteralSequenceExpression
         sequence: GTC
-  - type: TraversalBlock
-    orientation: forward
-    component: 
-      type: Allele
-      location:
-        type: SequenceLocation
-        start: 601
-        end: 602
-        sequenceReference:
-          type: SequenceReference
-          refgetAccession: SQ.9KdcA9ZpY1Cpvxvg8bMSLYDUpsX6GDLO
-          residueAlphabet: na
-          id: NC_000002.11
-      state:
-        type: LiteralSequenceExpression
-        sequence: C
+  - type: Allele
+    location:
+      type: SequenceLocation
+      start: 601
+      end: 602
+      sequenceReference:
+        type: SequenceReference
+        refgetAccession: SQ.9KdcA9ZpY1Cpvxvg8bMSLYDUpsX6GDLO
+        residueAlphabet: na
+        id: NC_000002.11
+    state:
+      type: LiteralSequenceExpression
+      sequence: C
   - type: TraversalBlock
     orientation: forward
     component: 
@@ -73,19 +67,16 @@ components:
             residueAlphabet: na
             id: NC_000001.10
           end: 1000
-  - type: TraversalBlock
-    orientation: forward
-    component: 
-      id: 3-prime-terminus
-      type: Terminus
-      location:
-        type: SequenceLocation
-        sequenceReference:
-          type: SequenceReference
-          refgetAccession: SQ.S_KjnFVz-FE7M0W6yoaUDgYxLPc1jyWU
-          residueAlphabet: na
-          id: NC_000001.10
-        start: 1000
+  - id: 3-prime-terminus
+    type: Terminus
+    location:
+      type: SequenceLocation
+      sequenceReference:
+        type: SequenceReference
+        refgetAccession: SQ.S_KjnFVz-FE7M0W6yoaUDgYxLPc1jyWU
+        residueAlphabet: na
+        id: NC_000001.10
+      start: 1000
 
 
 

diff --git a/schema/vrs/def/DerivativeMolecule.rst b/schema/vrs/def/DerivativeMolecule.rst
@@ -49,7 +49,7 @@ Some DerivativeMolecule attributes are inherited from :ref:`Variation`.
       - 1..1
       - MUST be "DerivativeMolecule".
    *  - components
-      - :ref:`IRI` | :ref:`TraversalBlock`
+      - :ref:`IRI` | :ref:`Allele` | :ref:`CisPhasedBlock` | :ref:`Terminus` | :ref:`TraversalBlock`
       - 2..m
       - The molecular components that constitute the derivative molecule.
    *  - circular

diff --git a/schema/vrs/def/TraversalBlock.rst b/schema/vrs/def/TraversalBlock.rst
@@ -41,7 +41,7 @@ Some TraversalBlock attributes are inherited from :ref:`gks.core-im:Entity`.
       - 1..1
       - MUST be "TraversalBlock".
    *  - component
-      - :ref:`Allele` | :ref:`CisPhasedBlock` | :ref:`Adjacency` | :ref:`Terminus`
+      - :ref:`Adjacency`
       - 0..1
       - The unoriented molecular variation component.
    *  - orientation

diff --git a/schema/vrs/json/DerivativeMolecule b/schema/vrs/json/DerivativeMolecule
@@ -67,6 +67,15 @@
          "ordered": true,
          "items": {
             "oneOf": [
+               {
+                  "$ref": "/ga4gh/schema/vrs/2.x/json/Allele"
+               },
+               {
+                  "$ref": "/ga4gh/schema/vrs/2.x/json/CisPhasedBlock"
+               },
+               {
+                  "$ref": "/ga4gh/schema/vrs/2.x/json/Terminus"
+               },
                {
                   "$ref": "/ga4gh/schema/vrs/2.x/json/TraversalBlock"
                },

diff --git a/schema/vrs/json/TraversalBlock b/schema/vrs/json/TraversalBlock
@@ -55,15 +55,6 @@
          "oneOf": [
             {
                "$ref": "/ga4gh/schema/vrs/2.x/json/Adjacency"
-            },
-            {
-               "$ref": "/ga4gh/schema/vrs/2.x/json/Allele"
-            },
-            {
-               "$ref": "/ga4gh/schema/vrs/2.x/json/CisPhasedBlock"
-            },
-            {
-               "$ref": "/ga4gh/schema/vrs/2.x/json/Terminus"
             }
          ]
       },

diff --git a/schema/vrs/vrs-source.yaml b/schema/vrs/vrs-source.yaml
@@ -581,6 +581,9 @@ $defs:
         items:
           oneOf:
           - $ref: "/ga4gh/schema/gks-common/1.x/core-im/json/IRI"
+          - $ref: "#/$defs/Allele"
+          - $ref: "#/$defs/CisPhasedBlock"
+          - $ref: "#/$defs/Terminus"
           - $ref: "#/$defs/TraversalBlock"
         description: >-
           The molecular components that constitute the derivative molecule.
@@ -603,8 +606,8 @@ $defs:
         - component
         - orientation
     description: >-
-      A component used to describe the orientation of a molecular variation within a
-      DerivativeMolecule.
+      A component used to describe the orientation of applicable molecular variation
+      within a DerivativeMolecule.
     properties:
       type:
         extends: type
@@ -615,10 +618,7 @@ $defs:
         description: >-
           The unoriented molecular variation component.
         oneOf:
-          - $ref: "#/$defs/Allele"
-          - $ref: "#/$defs/CisPhasedBlock"
           - $ref: "#/$defs/Adjacency"
-          - $ref: "#/$defs/Terminus"
       orientation:
         type: string
         description: >-