Merge branch '1.x' of https://github.com/ga4gh/cat-vrs into Issue-14

.gitmodules

@@ -1,4 +1,4 @@
 [submodule "submodules/vrs"]
 	path = submodules/vrs
 	url = https://github.com/ga4gh/vrs.git
-	branch = 2.0-alpha
+	branch = 2.x

Makefile

@@ -0,0 +1,40 @@
+PYV:=3.12
+VEDIR=venv/${PYV}
+
+############################################################################
+#= SETUP, INSTALLATION, PACKAGING
+
+#=> venv: make a Python 3 virtual environment
+.PHONY: venv/%
+venv/%:
+	python$* -m venv $@; \
+	source $@/bin/activate; \
+	python -m ensurepip --upgrade; \
+	pip install --upgrade pip setuptools
+
+#=> develop: install package in develop mode
+.PHONY: develop setup
+develop setup:
+	pip install -r .requirements.txt
+
+#=> devready: create venv, install prerequisites, install pkg in develop mode
+.PHONY: devready
+devready:
+	make ${VEDIR} && source ${VEDIR}/bin/activate && make develop
+	@echo '#################################################################################'
+	@echo '###  Do not forget to `source ${VEDIR}/bin/activate` to use this environment  ###'
+	@echo '#################################################################################'
+
+############################################################################
+#= TESTING
+# see test configuration in pyproject.toml
+
+#=> test: execute tests
+.PHONY: test
+test:
+	pytest tests/
+
+#=> doctest: execute documentation tests (requires extra data)
+.PHONY: doctest
+doctest:
+	pytest tests/ --doctest-modules

docs/source/appendices/index.rst

@@ -2,47 +2,16 @@ Appendices
 !!!!!!!!!!
 
 
-blah
+.. TODO:: Either add general landing page material for all appendices here or include the content of the different subsections directly.
 
 
 .. toctree::
    :maxdepth: 2
 
    design_decisions
-   development_process
-   future_plans
-
-   implementations
-   relationships
-   associating_annotations
-   equivalence
-   ga4gh_identifiers
-   truncated_digest_collision_analysis
-
    faq
    glossary
 
 
-.. .. toctree::
-    :maxdepth: 2
-    design_decisions
-    glossary
-    relationships
-    faq
-
-
-
-
-..    truncated_digest_collision_analysis
-..    future_plans
-..    implementations
-    equivalence
-    associating_annotations
-    ga4gh_identifiers
-    development_process
-    
-
-
-
 
 

docs/source/def

@@ -0,0 +1 @@
+../../schema/catvrs/def

docs/source/releases/1.0.rst → docs/source/releases/index.rst

@@ -1,5 +1,7 @@
-1.0
-!!!
+.. `Releases`:
+
+1.0 (pre-releases)
+!!!!!!!!!!!!!!!!!!
 
 1.0.0.04-2024.connect
 @@@@@@@@@@@@@@@@@@@@@

docs/source/rst_epilog

@@ -10,6 +10,8 @@
 .. _VRS Gene: https://vrs.ga4gh.org/en/latest/terms_and_model.html#gene
 
 .. |vrs| replace:: `VRS <https://vrs.ga4gh.org/>`__
+.. |vrs_yaml| replace:: `VRS YAML <https://github.com/ga4gh/vrs/tree/2.x/schema/vrs/vrs-source.yaml>`__
+.. |vrs_json| replace:: `VRS JSON <https://github.com/ga4gh/vrs/tree/2.x/schema/vrs/json>`__
 
 .. |eg| replace:: *e.g.,*
 .. |ie| replace:: *i.e.,*

docs/source/schema.rst

@@ -13,14 +13,14 @@ Machine Readable Specifications
 The machine readable Cat-VRS is written using `JSON Schema
 <https://json-schema.org/>`_.
 
-The schema itself is written in YAML (|vrs_yaml|) and converted to JSON
-(|vrs_json|).
+The schema itself is written in YAML (|vrs_yaml|) and converted to individual
+JSON files for each class in the schema (|vrs_json|).
 
 Contributions to the schema MUST be written in the YAML document.
 
 
 .. _CategoricalVariationSchemata:
-
+.. _CategoricalVariation:
 
 Categorical Variation Schemata
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@@ -33,32 +33,32 @@ PLEASE CHECK BACK IN THE FUTURE!
     :alt: An irresistably cute kittynaut beckoning you to enter the Cat-VRS.
     :align: center
 
-.. include:: defs/CategoricalVariation.rst
+.. include:: def/CategoricalVariation.rst
 
-.. _Canonical:
+.. _CanonicalAllele:
 
 Canonical Allele
 ################
 
-.. include:: defs/CanonicalAllele.rst
+.. include:: def/CanonicalAllele.rst
 
-.. _Described:
+.. _DescribedVariation:
 
 Described Variation
 ###################
 
-.. include:: defs/DescribedVariation.rst
+.. include:: def/DescribedVariation.rst
 
-.. _CatCNV:
+.. _CategoricalCnv:
 
 Categorical Copy Number
 #######################
 
-.. include:: defs/CategoricalCnv.rst
+.. include:: def/CategoricalCnv.rst
 
-.. _ProtConsequence:
+.. _ProteinSequenceConsequence:
 
 Protein Sequence Consequence
 ############################
 
-.. include:: defs/ProteinSequenceConsequence.rst
+.. include:: def/ProteinSequenceConsequence.rst

examples/proteinSequenceConsequence-ex1.yaml

@@ -1,13 +1,13 @@
 id: civic.mpid:33
 type: ProteinSequenceConsequence
 description: >-
-  EGFR L858R has long been recognized as a functionally significant mutation in cancer, 
-  and is one of the most prevalent single mutations in lung cancer. Best described in 
-  non-small cell lung cancer (NSCLC), the mutation seems to confer sensitivity to first 
-  and second generation TKI's like gefitinib and neratinib. NSCLC patients with this 
-  mutation treated with TKI's show increased overall and progression-free survival, as 
-  compared to chemotherapy alone. Third generation TKI's are currently in clinical trials 
-  that specifically focus on mutant forms of EGFR, a few of which have shown efficacy in 
+  EGFR L858R has long been recognized as a functionally significant mutation in cancer,
+  and is one of the most prevalent single mutations in lung cancer. Best described in
+  non-small cell lung cancer (NSCLC), the mutation seems to confer sensitivity to first
+  and second generation TKI's like gefitinib and neratinib. NSCLC patients with this
+  mutation treated with TKI's show increased overall and progression-free survival, as
+  compared to chemotherapy alone. Third generation TKI's are currently in clinical trials
+  that specifically focus on mutant forms of EGFR, a few of which have shown efficacy in
   treating patients that failed to respond to earlier generation TKI therapies.
 label: EGFR L858R
 definingContext: vrs.json#/ga4gh:VA.kgjrhgf84CEndyLjKdAO0RxN-e3pJjxA
@@ -16,7 +16,7 @@ members:
   - vrs.json#/ga4gh:VA.3_FsKSUHEdurPIw5gqpw6g0_Ga0TEXQh
   - vrs.json#/ga4gh:VA.zpv3dW34z8jioKL-NtbGc0fa9clsgAZT
   - vrs.json#/ga4gh:VA.BJOtfUhZMooMJUO4FjxHXTEimrKXtF0i
-aliases:
+alternativeLabels:
   - LEU858ARG
   - rs121434568
 mappings:

schema/catvrs/Makefile

@@ -2,6 +2,8 @@
 .DELETE_ON_ERROR:
 
 BUILD_DIR := build
+DEF_DIR := def
+JSON_DIR := json
 IMPORT_DIR := import
 
 vpath %tag $(BUILD_DIR)
@@ -38,3 +40,5 @@ prune-tag: ${TAGS}
 
 clean:
 	rm $(BUILD_DIR)/*
+	rm $(DEF_DIR)/*
+	rm $(JSON_DIR)/*

schema/catvrs/catvrs-source.yaml

@@ -5,15 +5,15 @@ type: object
 strict: true
 
 imports:
-  gks.core: ../gks-common/core-source.yaml
+  gks.common: ../gks-common/common-source.yaml
   vrs: ../vrs/vrs-source.yaml
 
 namespaces:
   vrs: ../vrs/vrs.yaml#/$defs/
-  gks.core: ../gks-common/core.yaml#/$defs/
+  gks.common: ../gks-common/common.yaml#/$defs/
 
 $defs:
-  # VRSATILE Categorical Variation are presented top-down. Everything rolls up to
+  # Categorical Variation are presented top-down. Everything rolls up to
   # CategoricalVariation, which is a polymorphic abstraction of many kinds of
   # categorical variation.
 
@@ -22,7 +22,7 @@ $defs:
   # =============================================================================
 
   CategoricalVariation:
-    inherits: gks.core:DomainEntity
+    inherits: gks.common:DomainEntity
     description: >-
       A representation of a categorically-defined domain for variation, in which individual 
       contextual variation instances may be members of the domain.
@@ -41,7 +41,7 @@ $defs:
         items:
           oneOf:
             - $refCurie: vrs:Variation
-            - $refCurie: gks.core:IRI
+            - $refCurie: gks.common:IRI
       constraints:
         type: array
         ordered: false
@@ -60,14 +60,14 @@ $defs:
       of congruent Protein Alleles that share the same altered codon(s).
     properties:
       type:
-        type: string
+        extends: type
         const: ProteinSequenceConsequence
         default: ProteinSequenceConsequence
         description: 'MUST be "ProteinSequenceConsequence"'
       definingContext:
         oneOf:
           - $refCurie: vrs:Allele
-          - $refCurie: gks.core:IRI
+          - $refCurie: gks.common:IRI
         description: >-
           The `VRS Allele <https://vrs.ga4gh.org/en/2.0/terms_and_model.html#allele>`_
           object that is congruent with (projects to the same codons) as alleles on other protein reference 
@@ -86,14 +86,14 @@ $defs:
     type: object
     properties:
       type:
-        type: string
+        extends: type
         const: CanonicalAllele
         default: CanonicalAllele
         description: 'MUST be "CanonicalAllele"'
       definingContext:
         oneOf:
           - $refCurie: vrs:Allele
-          - $refCurie: gks.core:IRI
+          - $refCurie: gks.common:IRI
         description: >-
           The `VRS Allele <https://vrs.ga4gh.org/en/2.0/terms_and_model.html#allele>`_
           object that is congruent with variants on alternate reference sequences.
@@ -113,7 +113,7 @@ $defs:
       member CNVs.
     properties:
       type:
-        type: string
+        extends: type
         const: CategoricalCnv
         default: CategoricalCnv
         description: 'MUST be "CategoricalCnv"'
@@ -162,7 +162,7 @@ $defs:
       to indicate how a categorical variation concept should be evaluated for matching variants.
     properties:
       type:
-        type: string
+        extends: type
         const: DescribedVariation
         default: DescribedVariation
         description: 'MUST be "DescribedVariation"'
@@ -460,10 +460,10 @@ $defs:
   # Top-level Categorical Variation concepts
   # =============================================================================
 
-  # CategoricalVariant:
-  #   inherits: gks.core:DomainEntity
-  #   description: >-
-  #     A top-level representation of a categorically-defined domain for variation across one or multiple biological levels in which individual contextual variants may be members of the domain.
+  CategoricalVariant:
+    inherits: gks.common:DomainEntity
+    description: >-
+      A top-level representation of a categorically-defined domain for variation across one or multiple biological levels in which individual contextual variants may be members of the domain.
     # type: object
     # properties:
     #   id:
@@ -482,7 +482,7 @@ $defs:
     #     type: array
     #     ordered: true
     #     items:
-    #       - $refExtension: gks.core:Extension
+    #       - $refExtension: gks.common:Extension
 
 
 

schema/catvrs/def/CanonicalAllele.rst

@@ -19,40 +19,40 @@ Some CanonicalAllele attributes are inherited from :ref:`CategoricalVariation`.
        *  - id
           - string
           - 0..1
-          - The 'logical' identifier of the entity in the system of record, e.g. a UUID. This 'id' is  unique within a given system. The identified entity may have a different 'id' in a different  system, or may refer to an 'id' for the shared concept in another system (e.g. a CURIE).
+          - The 'logical' identifier of the entity in the system of record, e.g. a UUID. This 'id' is unique within a given system. The identified entity may have a different 'id' in a different system, or may refer to an 'id' for the shared concept in another system (e.g. a CURIE).
        *  - label
           - string
           - 0..1
-          - A primary label for the entity.
+          - A primary name for the entity.
        *  - description
           - string
           - 0..1
           - A free-text description of the entity.
+       *  - alternativeLabels
+          - string
+          - 0..m
+          - Alternative name(s) for the Entity.
        *  - extensions
-          - `Extension <../gks-common/core.json#/$defs/Extension>`_
+          - `Extension <../gks-common/common.json#/$defs/Extension>`_
           - 0..m
-          - 
+          - A list of extensions to the entity. Extensions are not expected to be natively understood, but may be used for pre-negotiated exchange of message attributes between systems.
        *  - mappings
-          - `Mapping <../gks-common/core.json#/$defs/Mapping>`_
+          - `ConceptMapping <../gks-common/common.json#/$defs/ConceptMapping>`_
           - 0..m
-          - 
+          - A list of mappings to concepts in terminologies or code systems. Each mapping should include a coding and a relation.
+       *  - members
+          - `Variation <../vrs/vrs.yaml#/$defs/Variation>`_ | `IRI <../gks-common/common.yaml#/$defs/IRI>`_
+          - 0..m
+          - A non-exhaustive list of VRS variation contexts that satisfy the constraints of this categorical variant.
        *  - type
           - string
           - 1..1
           - MUST be "CanonicalAllele"
-       *  - aliases
-          - string
-          - 0..m
-          - Aliases are alternate labels for a Domain Entity.
-       *  - members
-          - `Variation <../vrs/vrs.yaml#/$defs/Variation>`_ | `IRI <../gks-common/core.yaml#/$defs/IRI>`_
-          - 0..m
-          - A non-exhaustive list of VRS variation contexts that satisfy the constraints of this categorical variant.
        *  - constraints
           - :ref:`Constraint`
           - 0..m
           - 
        *  - definingContext
-          - `Allele <../vrs/vrs.yaml#/$defs/Allele>`_ | `IRI <../gks-common/core.yaml#/$defs/IRI>`_
+          - `Allele <../vrs/vrs.yaml#/$defs/Allele>`_ | `IRI <../gks-common/common.yaml#/$defs/IRI>`_
           - 1..1
           - The `VRS Allele <https://vrs.ga4gh.org/en/2.0/terms_and_model.html#allele>`_ object that is congruent with variants on alternate reference sequences.