Issue 404

.gitignore

@@ -3,3 +3,4 @@ __pycache__
 archive
 docs/build
 venv
+pyproject.toml

.requirements.txt

@@ -4,4 +4,5 @@ jsonschema==3.2.0
 ipython
 pyyaml
 ga4gh.gks.metaschema==0.2.0rc4
-sphinx ~= 3.5
+sphinx ~= 4.5
+sphinx-rtd-theme ~= 1.2

docs/source/terms_and_model.rst

@@ -368,22 +368,21 @@ Systemic Variation
 
 .. include:: defs/SystemicVariation.rst
 
-.. _AbsoluteCopyNumber:
+.. _CopyNumberCount:
 
-AbsoluteCopyNumber
-$$$$$$$$$$$$$$$$$$
+CopyNumberCount
+$$$$$$$$$$$$$$$
 
-*Absolute Copy Number Variation* captures the copies of a molecule within a
-genome, and can be used to express concepts such as amplification
-and copy loss. Copy Number Variation has conflated meanings in the
+*Copy Number Count* captures the integral copies of a molecule within a
+genome. Copy Number Count has conflated meanings in the
 genomics community, and can mean either (or both) the notion of copy
 number *in a genome* or copy number *on a molecule*. VRS separates
 the concerns of these two types of statements; this concept is a type
 of :ref:`SystemicVariation` and so describes the number of copies in a
 genome. The related :ref:`MolecularVariation` concept can be expressed
 as an :ref:`Allele` with a :ref:`RepeatedSequenceExpression`.
 
-.. include:: defs/AbsoluteCopyNumber.rst
+.. include:: defs/CopyNumberCount.rst
 
 **Examples**
 
@@ -401,21 +400,24 @@ Two, three, or four total copies of BRCA1:
         "gene_id": "ncbigene:348",
         "type": "Gene"
       },
-      "type": "AbsoluteCopyNumber"
+      "type": "CopyNumberCount"
     }
 
-.. _RelativeCopyNumber:
+.. _CopyNumberChange:
 
-RelativeCopyNumber
-$$$$$$$$$$$$$$$$$$
+CopyNumberChange
+$$$$$$$$$$$$$$$$
 
-*Relative Copy Number Variation* captures a classification of copies
+*Copy Number Change* captures a categorization of copies
 of a molecule within a system, relative to a baseline. These types
 of Variation are common outputs from CNV callers, particularly in the
-somatic domain where Absolute Copy Counts are difficult to estimate
-and less useful in practice than relative statements.
+somatic domain where integral :ref:`CopyNumberCount` are difficult to
+estimate and less useful in practice than relative statements. Somatic CNV
+callers typically express changes as relative statements, and many HGVS
+expressions submitted to express copy number variation are interpreted to be
+relative copy changes.
 
-.. include:: defs/RelativeCopyNumber.rst
+.. include:: defs/CopyNumberChange.rst
 
 **Examples**
 
@@ -424,12 +426,12 @@ Low-level copy gain of BRCA1:
 .. parsed-literal::
 
     {
-      "relative_copy_class": "low-level gain",
+      "relative_copy_class": "EFO_0030071", # low-level gain
       "subject": {
-        "gene_id": "ncbigene:348",
+        "gene_id": "ncbigene:348",          # BRCA1 gene
         "type": "Gene"
       },
-      "type": "RelativeCopyNumber"
+      "type": "CopyNumberChange"
     }
 
 .. _genotype:

schema/defs/vrs/CopyNumberChange.rst

@@ -0,0 +1,34 @@
+**Computational Definition**
+
+An assessment of the copy number of a :ref:`Location` or a :ref:`Feature` within a system (e.g. genome, cell,  etc.) relative to a baseline ploidy.
+
+**Information Model**
+
+Some CopyNumberChange attributes are inherited from :ref:`Variation`.
+
+.. list-table::
+   :class: clean-wrap
+   :header-rows: 1
+   :align: left
+   :widths: auto
+
+   *  - Field
+      - Type
+      - Limits
+      - Description
+   *  - _id
+      - :ref:`CURIE`
+      - 0..1
+      - Variation Id. MUST be unique within document.
+   *  - type
+      - string
+      - 1..1
+      - MUST be "CopyNumberChange"
+   *  - subject
+      - :ref:`Location` | :ref:`CURIE` | :ref:`Feature`
+      - 1..1
+      - A location for which the number of systemic copies is described.
+   *  - copy_assessment
+      - string
+      - 1..1
+      - MUST be one of "EFO_0030069" (complete genomic loss), "EFO_0020073" (high-level loss),  "EFO_0030068" (low-level loss), "EFO_0030067" (loss), "EFO_0030064" (regional base ploidy),  "EFO_0030070" (gain), "EFO_0030071" (low-level gain), "EFO_0030072" (high-level gain).

schema/defs/vrs/AbsoluteCopyNumber.rst → schema/defs/vrs/CopyNumberCount.rst

@@ -1,10 +1,10 @@
 **Computational Definition**
 
-The absolute count of discrete copies of a :ref:`Location`, within a system (e.g. genome, cell, etc.).
+The absolute count of discrete copies of a :ref:`Location` or :ref:`Feature`, within a system (e.g. genome, cell, etc.).
 
 **Information Model**
 
-Some AbsoluteCopyNumber attributes are inherited from :ref:`Variation`.
+Some CopyNumberCount attributes are inherited from :ref:`Variation`.
 
 .. list-table::
    :class: clean-wrap
@@ -23,9 +23,9 @@ Some AbsoluteCopyNumber attributes are inherited from :ref:`Variation`.
    *  - type
       - string
       - 1..1
-      - MUST be "AbsoluteCopyNumber"
+      - MUST be "CopyNumberCount"
    *  - subject
-      - :ref:`Location` | :ref:`CURIE`
+      - :ref:`Location` | :ref:`CURIE` | :ref:`Feature`
       - 1..1
       - A location for which the number of systemic copies is described.
    *  - copies

schema/ga4gh.yaml

@@ -25,8 +25,8 @@ identifiers:
     Text: VT
     Genotype: GT
     Haplotype: VH
-    AbsoluteCopyNumber: VAC
-    RelativeCopyNumber: VRC
+    CopyNumberCount: CN
+    CopyNumberChange: CX
     SequenceLocation: VSL
     ChromosomeLocation: VCL
 

schema/vrs-source.yaml

@@ -71,7 +71,8 @@ definitions:
       A Variation of multiple molecules in the context of a system, e.g.
       a genome, sample, or homologous chromosomes.
     oneOf:
-      - $ref: "#/definitions/CopyNumber"
+      - $ref: "#/definitions/CopyNumberCount"
+      - $ref: "#/definitions/CopyNumberChange"
       - $ref: "#/definitions/Genotype"
     discriminator:
       propertyName: type
@@ -187,64 +188,64 @@ definitions:
   # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   # SystemicVariation
 
-  CopyNumber:
+  CopyNumberCount:
     inherits: SystemicVariation
-    description: >-
-      The copies of :ref:`Location` in a system, expressed as an absolute integer
-      quantity (:ref:`AbsoluteCopyNumber`) or a qualitative description of copies 
-      relative to a baseline state (:ref:`RelativeCopyNumber`).
-    heritable_properties:
-      subject:
-        oneOf:
-          - $ref: "#/definitions/Location"
-          - $ref: "#/definitions/CURIE"
-        description: >-
-          A location for which the number of systemic copies is described.
-    heritable_required: [ "subject" ]
-
-  AbsoluteCopyNumber:
-    inherits: CopyNumber
     type: object
-    maturity: draft
     description: >-
-      The absolute count of discrete copies of a :ref:`Location`,
+      The absolute count of discrete copies of a :ref:`Location` or :ref:`Feature`,
       within a system (e.g. genome, cell, etc.).
     properties:
       type:
         type: string
-        const: "AbsoluteCopyNumber"
-        default: "AbsoluteCopyNumber"
+        const: "CopyNumberCount"
+        default: "CopyNumberCount"
         description: >-
-          MUST be "AbsoluteCopyNumber"
+          MUST be "CopyNumberCount"
+      subject:
+        oneOf:
+          - $ref: "#/definitions/Location"
+          - $ref: "#/definitions/CURIE"
+          - $ref: "#/definitions/Feature"
+        description: >-
+          A location for which the number of systemic copies is described.
       copies:
         oneOf:
           - $ref: "#/definitions/Number"
           - $ref: "#/definitions/IndefiniteRange"
           - $ref: "#/definitions/DefiniteRange"
         description: >-
           The integral number of copies of the subject in a system
-    required: [ "copies" ]
+    required: [ "subject", "copies" ]
 
-  RelativeCopyNumber:
-    inherits: CopyNumber
+  CopyNumberChange:
+    inherits: SystemicVariation
     type: object
     maturity: draft
     description: >-
-      The copies of a :ref:`Location` within a system (e.g. genome, cell, etc.)
-      relative to a baseline state.
+      An assessment of the copy number of a :ref:`Location` or a :ref:`Feature` within a system (e.g. genome, cell, 
+      etc.) relative to a baseline ploidy.
     properties:
       type:
         type: string
-        const: "RelativeCopyNumber"
-        default: "RelativeCopyNumber"
+        const: "CopyNumberChange"
+        default: "CopyNumberChange"
         description: >-
-          MUST be "RelativeCopyNumber"
-      relative_copy_class:
+          MUST be "CopyNumberChange"
+      subject:
+        oneOf:
+          - $ref: "#/definitions/Location"
+          - $ref: "#/definitions/CURIE"
+          - $ref: "#/definitions/Feature"
+        description: >-
+          A location for which the number of systemic copies is described.
+      copy_assessment:
         type: string
-        enum: [ "complete loss", "partial loss", "copy neutral", "low-level gain", "high-level gain" ]
+        enum: [ "EFO_0030069", "EFO_0020073", "EFO_0030068", "EFO_0030067", "EFO_0030064", "EFO_0030070", "EFO_0030071", "EFO_0030072" ]
         description: >-
-          MUST be one of "complete loss", "partial loss", "copy neutral", "low-level gain" or "high-level gain".
-    required: [  "relative_copy_class" ]
+          MUST be one of "EFO_0030069" (complete genomic loss), "EFO_0020073" (high-level loss), 
+          "EFO_0030068" (low-level loss), "EFO_0030067" (loss), "EFO_0030064" (regional base ploidy), 
+          "EFO_0030070" (gain), "EFO_0030071" (low-level gain), "EFO_0030072" (high-level gain).
+    required: [  "subject", "copy_assessment" ]
 
   Genotype:
     inherits: SystemicVariation