Add design decisions and term definitions for CopyNumberChange (#644)

* init 2.0.1 change log
* add controlled vocabulary from EFO
* correct patch-level $id error
* write design decision for enums over mappableconcept

Author: ahwagner

docs/source/appendices/design_decisions.rst

@@ -6,7 +6,7 @@ Design Decisions
 The following design decisions were made in the development of the VRS:
 
 GA4GH Inherent Properties over Value Objects
---------------------------------------------
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
 In VRS 1.0 we operated under the principle that all identifiable objects in VRS (e.g. Allele, SequenceLocation, etc.)
 would be *value objects*. This meant that they should be immutable and contain only required fields that are
@@ -23,7 +23,7 @@ As a result, we had to introduce a new field in the digest model called *ga4gh.i
 in the section on :ref:`ga4gh-inherent-properties`.
 
 IRIs over CURIEs
-----------------
+@@@@@@@@@@@@@@@@
 
 In VRS 2.0 we moved away from the use of CURIEs in favor of :ref:`iriReference`. Several factors played a role in
 this decision.
@@ -34,13 +34,14 @@ endpoints, or documentation that may not persist as messages are exchanged betwe
 in GKS specs now use IRIs to reference objects explicitly.
 
 IRI-References over IRIs
-------------------------
+@@@@@@@@@@@@@@@@@@@@@@@@
+
 We opted for the general use of IRI-References as a way to provide a more flexible approach to the use of IRIs
 in most GKS message structures. IRI-references (relative IRIs) benefit the users allow for compact representation
 of concepts that are accessible within a system (e.g. a directory structure or web API).
 
 VRS identifier syntax and versioning
-------------------------------------
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
 The :ref:`versioning` section describes the versioning and release naming conventions for the VRS product.
 Approved releases will be assigned to the version number alone, but connect, ballot and snapshot releases will
@@ -59,7 +60,7 @@ As an example, the Github JSON Schema URL ($id) for the VRS 2.0.0 Allele is:
 
   {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://w3id.org/ga4gh/schema/vrs/2.0/json/Allele",
+    "$id": "https://w3id.org/ga4gh/schema/vrs/2.0.0/json/Allele",
     ...
   }
 
@@ -88,3 +89,19 @@ the following syntax:
 .. code-block::
 
   https://w3id.org/ga4gh/vrs/VA.Oop4kjdTtKcg1kiZjIJAAR3bp7qi4aNT
+
+Use of value sets for VRS computed digests
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+The GKS Core model contains a ``MappableConcept`` data model which is usable in
+places where one would expect general, externally-defined concepts such as
+genes, diseases, or therapeutics. In VRS, we intentionally define value sets
+instead of using the ``MappableConcept`` model in places where such concepts are
+used in calculated a computed digest.
+
+For example, the :ref:`CopyNumberChange` model has a ``copyChange`` field that
+describes whether the variant `Location` is systematically observed as a low-level
+or high-level gain or loss. These concepts, though defined in the Experimental Factor
+Ontology, are maintained internally such that changes to these concepts in EFO will
+not affect their use in VRS (and therefore not affect the computed digests of
+CopyNumberChange objects).

docs/source/concepts/SystemicVariation/CopyNumberChange.rst

@@ -10,6 +10,29 @@ Definition and Information Model
 
 .. include::  ../../def/vrs/CopyNumberChange.rst
 
+Copy Change term definitions
+############################
+
+The `CopyChange` attribute uses a valueset derived from the
+`Experimental Factor Ontology (EFO) <https://www.ebi.ac.uk/efo/>`_:
+
+* **gain** (`EFO:0030070 <http://www.ebi.ac.uk/efo/EFO_0030070>`_ - *copy number gain*):
+  Assessment of genomic copy number gain.
+    * **high-level gain** (`EFO:0030072 <http://www.ebi.ac.uk/efo/EFO_0030072>`_ - *high-level copy number gain*):
+      Assessment of high-level genomic copy number gain.
+    * **low-level gain** (`EFO:0030071 <http://www.ebi.ac.uk/efo/EFO_0030071>`_ - *low-level copy number gain*):
+      Assessment of low-level genomic copy number gain.
+* **regional base ploidy** (`EFO:0030064 <http://www.ebi.ac.uk/efo/EFO_0030064>`_ - *regional base ploidy*):
+  Copy number assessment of regional base ploidy.
+* **loss** (`EFO:0030067 <http://www.ebi.ac.uk/efo/EFO_0030067>`_ - *copy number loss*):
+  Assessment of genomic copy number loss.
+    * **low-level loss** (`EFO:0030068 <http://www.ebi.ac.uk/efo/EFO_0030068>`_ -
+      *low-level copy number loss*): Assessment of low-level genomic copy number loss.
+    * **high-level loss** (`EFO:0020073 <http://www.ebi.ac.uk/efo/EFO_0020073>`_ -
+      *high-level copy number loss*): Assessment of high-level genomic copy number loss.
+        * **complete genomic loss** (`EFO:0030069 <http://www.ebi.ac.uk/efo/EFO_0030069>`_ -
+          *complete genomic deletion*: Assessment of complete genomic deletion.
+
 Example
 @@@@@@@
 
@@ -18,7 +41,7 @@ Example
   {
     "id": "ga4gh:CX.2_fT_6-IpUm5aS0wp8ZAkJ01MCE569L2",
     "type": "CopyNumberChange",
-    "copyChange": "EFO:0030071",
+    "copyChange": "low-level gain",
     "location": {
       "sequenceReference": {
         "refgetAccession": "SQ.jdEWLvLvT8827O59m1Agh5H3n6kTzBsJ",

docs/source/releases/2.0.rst

@@ -22,3 +22,5 @@ Summary of Changes
 ##################
 
   * updates :ref:`CopyNumberChange` draft to use named enum in lieu of MappableConcept
+  * adds controlled vocabulary of `CopyNumberChange` enum to class definitions
+  * adds design decision for use of value sets over MappableConcept in VRS