SequenceLocation optional reference documentation (#618)

* closes #564
ga4gh · Dec 16, 2024 · e3de2b3 · e3de2b3
1 parent 5dffe02
commit e3de2b3
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 4 deletions.
diff --git a/docs/source/concepts/LocationAndReference/SequenceLocation.rst b/docs/source/concepts/LocationAndReference/SequenceLocation.rst
@@ -55,7 +55,10 @@ The "Ref" Allele
 
 In some variant representation formats (e.g. HGVS, VCF) sequence variants are described by both their "reference"
 (ref) and "alternate" (alt) alleles. When representing an Allele with VRS v2, it is also possible to describe the
-ref sequence (derived from the :ref:SequenceReference at the location) using the *sequence* property.
+ref sequence (derived from the :ref:`SequenceReference` at the location) using the *sequence* property.
+
+The ``sequence`` property is **for describing the sequence derived from the SequenceLocation**, and is not a 
+substitute for the ``sequenceReference`` property that references the sequence on which the location is defined.
 
 .. admonition:: New in v2
 
@@ -85,3 +88,12 @@ chromosome sequence to which it aligns. VRS intentionally does not allow for *st
 that use an offset system to represent sequence not found on the :ref:`SequenceReference`.
 
 .. TODO:: Describe and add a ref to an intronic variant profile
+
+CisPhasedBlocks and the Inferred SequenceReference
+##################################################
+
+When a :ref:`SequenceReference` is provided in a :ref:`CisPhasedBlock`, it is defined that all member
+:ref:`Allele` objects occur on that sequence. Consequently, the ``SequenceLocation`` object for each 
+:ref:`Allele` does not need to populate the ``sequenceReference`` property. There may be other contexts 
+where this optional property may be omitted, but when this is done there SHOULD be a means of inferring 
+the content of this property (as is explicitly described in :ref:`CisPhasedBlock`).
diff --git a/docs/source/concepts/LocationAndReference/SequenceReference.rst b/docs/source/concepts/LocationAndReference/SequenceReference.rst
@@ -16,17 +16,17 @@ such as the alphabet used (nucleic acid or amino acid), if the sequence represen
 and labels used to describe the sequence.
 
 Definition and Information Model
-################################
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
 .. include::  ../../def/vrs/SequenceReference.rst
 
 Example
-#######
+@@@@@@@
 
 .. code-block:: json
 
     {
       "type": "SequenceReference",
       "refgetAccession": "SQ.F-LrLMe1SRpfUZHkQmvkVKFEGaoDeHul",
       "label": "NC_000007.14"
-    }    
+    }