Merge remote-tracking branch 'origin/v1' into 191-documentation-refactor

Author: brendanreardon

.github/pull_request_template.md

@@ -1,14 +1,17 @@
-Link to the corresponding Issue.
+## Link to the corresponding Issue
 
-Summary of the Pull Request.
+## Summary of the Pull Request
 
-Pull Request checklist:
-- [ ] Does the title of this Pull Request reference the corresponding Issue?
-- [ ] Is the branch validating against pre-commit hooks? Run `pre-commit run --all-files` from the root directory.
-- [ ] Is the branch passing tests? Run `pytest tests/` from the root directory.
+## Pull Request checklist
 
-If the schema or examples were contributed to:
-- [ ] Were the schema def/ and json/ files recompiled and committed? Run `cd schema; make all` from the root directory.
-- [ ] If constraints or recipes were added, have they been added to the readthedocs? To do so, you can revise the appropriate file within `docs/source/concepts/`.
-- [ ] Has documentation been regenerated and committed? Run `cd docs; make clean watch &` from the root directory to compile documentation.
-- [ ] Have tests been created or updated?
+### Required
+- [ ] The title of this Pull Request accurately reflects the scope and content of the linked Issue.
+- [ ] The branch passes all pre-commit hooks (Run `pre-commit run --all-files` from the root directory).
+- [ ] The branch passes all tests (Run `pytest tests/` from the root directory).
+
+### Required if the schema or examples were contributed to
+- [ ] The schema `def/` and `json/` files have been recompiled and committed (Run `cd schema; make all` from the root directory).
+- [ ] Tests have been created or updated.
+- [ ] Schema changes have been documented (existing files updated or new files created in `docs/source/`).
+- [ ] Any new schema definition `.rst` files have been registered in the documentation structure.
+- [ ] Documentation has been regenerated and committed (Run `cd docs; make clean watch &` from the root directory to compile documentation).

.gitmodules

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

.readthedocs.yaml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.11"
+    python: "3.12"
 
 submodules:
   include: all
@@ -14,4 +14,4 @@ sphinx:
 
 python:
   install:
-    - requirements: docs/source/requirements.txt
+    - requirements: .requirements.txt

.requirements.txt

@@ -1,8 +1,15 @@
-pytest
-sphinx ~= 7.2
-sphinx-rtd-theme ~= 1.2
-pyyaml
-ga4gh.gks.metaschema==0.3.2
+# Schema validation
+ga4gh.gks.metaschema == 0.3.2
 jsonschema
+pyyaml
 referencing
+
+# Development and testing
+pytest
 pre-commit
+
+# ReadtheDocs
+jinja2 == 3.1.6
+sphinx ~= 8.1.3
+sphinx-rtd-theme ~= 3.0.2
+sphinx_toolbox == 3.9.0

README.md

@@ -1,6 +1,6 @@
 # Categorical Variation Representation Specification (Cat-VRS)
 
-[![Read the Docs](https://img.shields.io/readthedocs/vr-spec/1.1)](https://cat-vrs.readthedocs.io/en/latest/)
+[![Read the Docs](https://img.shields.io/readthedocs/cat-vrs)](https://cat-vrs.readthedocs.io/en/latest/)
 
 **Cat-VRS 1.0.0 Trial Use Review November 2024 - join in [here](https://github.com/ga4gh/cat-vrs/discussions/86)**!
 

docs/source/appendices/design_decisions.rst

@@ -1,7 +1,7 @@
 .. _design-decisions:
 
 Design Decisions
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!!!!!!!!!!!!!!!!
 
 Cat-VRS contributors confronted numerous trade-offs in developing this specification. As these trade-offs may not be apparent to outside readers, this section highlights the most significant ones and the rationale for our design decisions, including the following.
 
@@ -21,17 +21,9 @@ Decisions are labeled based on their maturity status based on the :ref:`maturity
 Because maturity is a function of (1) the breadth of model adoption and (2) expected stability, rather than a function of how fundamental a concept is to the model, the maturity status property is entirely orthogonal to the impact of a decision on Cat-VRS.
 
 
-.. toctree::
-   :maxdepth: 3
-   :includehidden:
-
-   major_impact
-   medium_impact
-   minor_impact
-   general_principles
-
-
-
+.. contents::
+   :local:
+   :depth: 1
 
 
 .. major_impact
@@ -42,7 +34,8 @@ Major Impact
 
 .. hyperintensional_catvars
 
-**Treatment of CatVars as ((Hyper)intensional) Set-Theoretic Objects**
+Treatment of CatVars as ((Hyper)intensional) Set-Theoretic Objects
+==================================================================
 
 **Decision:**
 The group decided to model categorical variants as `hyperintensional <https://plato.stanford.edu/entries/hyperintensionality/>`_ set objects to address the complexities of categorical data representation.
@@ -77,7 +70,8 @@ For example, an extensional set describing *BRAF*  p.V600E would need to include
 
 .. constraint_model
 
-**Adoption of a Constraint-Based Model Instead of a Fixed Top-Down Typology of Data Classes**
+Adoption of a Constraint-Based Model Instead of a Fixed Top-Down Typology of Data Classes
+=========================================================================================
 
 **Decision:**
 The group decided to use a `constraint-based model <https://github.com/ga4gh/cat-vrs/discussions/22>`_, defining categorical variants dynamically in a bottom-up fashion based on set constraints rather than in a rigid top-down hierarchy of variant types.
@@ -111,7 +105,8 @@ Medium Impact
 
 .. constraint_array_of_anded_elements
 
-**Constraints as an Array of implicitly ANDed elements**
+Constraints as an Array of implicitly ANDed elements
+====================================================
 
 **Decision:**
 The group decided that the individual *constraints* in the array of the constraints property are to be treated as implicitly ANDed together, and that no other boolean relations should be used in the context of the *CategoricalVariant* data class.
@@ -129,7 +124,8 @@ One property of the base *CategoricalVariant* class in the constraint model is c
 
 .. including_recipes
 
-**Including Recipes in the Cat-VRS Specification**
+Including Recipes in the Cat-VRS Specification
+==============================================
 
 **Decision:**
 The group decided to include recipes in Cat-VRS which illustrate representation of genomic variant types under the constraint model.
@@ -147,7 +143,8 @@ It is intended that implementations of Cat-VRS will allow for variants to be sea
 
 .. machine_readable_spec
 
-**Machine Readable Specifications**
+Machine Readable Specifications
+===============================
 
 **Decision:**
 The group decided to adopt several repository and organizational conventions to ensure a single source of truth during development and ensure that the schema is readily computable:
@@ -169,7 +166,8 @@ These decisions bring Cat-VRS development in line with accepted best practices i
 
 .. separating_copycount_and_copychange
 
-**Separating CopyNumberConstraint into CopyCountConstraint and CopyChangeConstraint**
+Separating CopyNumberConstraint into CopyCountConstraint and CopyChangeConstraint
+=================================================================================
 
 **Decision:**
 The original model had a single copy number constraint, which was later split into two distinct constraints: the *CopyCountConstraint* (absolute copy numbers) and *CopyChangeConstraint* (relative changes such as amplifications and deletions).
@@ -190,7 +188,8 @@ Separating these two constraints ensures greater precision in representing categ
 
 .. separating_definingallele_and_defininglocation
 
-**Separating DefiningContextConstraint into DefiningAlelleConstraint and DefiningLocationConstraint**
+Separating DefiningContextConstraint into DefiningAlelleConstraint and DefiningLocationConstraint
+=================================================================================================
 
 **Decision:**
 The group decided to split up the single combined *DefiningContextConstraint* into a *DefiningAlleleConstraint* and separate *DefiningLocationConstraint*.
@@ -204,45 +203,38 @@ This decision was driven by three primary considerations: (1) the need for great
 
 #. **Compatibility with existing genomic standards:** Existing GKS standards like VRS and knowledgebases like ClinVar treat sequence (location-state) variants and location variants separately. A single *DefiningContextConstraint* was somewhat misaligned with these models, making interoperability more challenging.
 
-
 Splitting this constraint allows the model to explicitly define variants based on location, sequence, or both while allowing for smoother integration across implementations by mirroring representation in other well established resources.
 
 **Citations:**
 
 *  `2024-11-19 meeting minutes <https://docs.google.com/document/d/1oI4ir4OzXFvhZNbMVEX-RHGAQ-d2K4lAKP-7lf-uzPc/edit?tab=t.0#heading=h.hd9lu8gw3jh9>`_, this was primarily discussed in person during a pre-conference hackathon before ASHG
 
-
-
 .. using_gks_maturity_model
 
-**Utilization of semantic versioning and the GKS maturity model**
+Utilization of semantic versioning and the GKS maturity model
+=============================================================
 
 **Decision:**
 The group decided to adopt standard semantic versioning practices and to indicate data class maturity in compliance with the :ref:`maturity-model`.
 
-
 **Rationale:**
 
 These decisions bring Cat-VRS in compliance with generally accepted best practices in the GKS workstream and improve transparency.
 
 **Citations:**
 
-
 *  `2023-10-25 meeting minutes <https://docs.google.com/document/d/1oI4ir4OzXFvhZNbMVEX-RHGAQ-d2K4lAKP-7lf-uzPc/edit?tab=t.0#heading=h.8xxp7lqoun48>`_
 
 *  `2023-10-11 meeting minutes <https://docs.google.com/document/d/1oI4ir4OzXFvhZNbMVEX-RHGAQ-d2K4lAKP-7lf-uzPc/edit?tab=t.0#heading=h.cmwm638mk3jb>`_
 
-
-
 .. generalizing_genecontextconstraint
 
-**Generalization of GeneContextConstriant into FeatureContextConstraint**
+Generalization of GeneContextConstriant into FeatureContextConstraint
+=====================================================================
 
 **Decision:**
 The specification originally proposed a *GeneContextConstraint* to capture variation knowledge tied to a specific gene, but this constraint was later broadened into a *FeatureContextConstraint* to include regulatory elements, pseudogenes, and other sequence-related features.
 
-
-
 **Rationale:**
 
 This change was necessary to generalize the model and improve modularity, ensuring that Cat-VRS supports diverse genomic elements beyond strictly defined genes. It also aligns better with other genomic standardization efforts and accommodates structural variants that do not map directly to specific genes​; for example, protein contexts such as “Estrogen Receptor (ER)”. Furthermore, FeatureContext better allows for catvar harmonization across different gene name-space conventions, as these change over time and between organizations. For example, in an older refseq version, *DUXL4* was considered as pseudogene, but in the current refseq version it is not recognized as a gene (or pseudogene) at all.
@@ -267,7 +259,8 @@ Minor Impact
 
 .. relations_and_mappings
 
-**Distinction between Relations and Mappings**
+Distinction between Relations and Mappings
+==========================================
 
 **Decision:**
 Relations refer to structured transformations to the underlying variant, such as translating a transcript sequence into an amino acid sequence. Mappings refer to homomorphisms of coded variant concepts between different codings systems and ontologies, for example, mapping the property of protein gain-of-function EFO code to that of a protein hypermorphism in SO.
@@ -288,7 +281,8 @@ The group followed existing practices in other GKS standards for relations and m
 
 .. members_are_non-exhaustive
 
-**Inclusion of Members as non-exhaustive array of contextual variants**
+Inclusion of Members as non-exhaustive array of contextual variants
+===================================================================
 
 **Decision:**
 Items in the *members* property constitute representative examples of GA4GH Variation Representation Specification (VRS) Variations that satisfy the constraints of a given categorical variant. It is neither required nor expected for *members* to contain an exhaustive list of representative VRS variants.
@@ -309,7 +303,8 @@ Because catvars are `defined by their properties (constraints), <https://docs.go
 
 .. name_as_a_non-required_field
 
-**Name as a non-required field**
+Name as a non-required field
+============================
 
 **Decision:**
 The *name* property in the *CategoricalVariant* class is an optional (but not required) field for *CategoricalVariant*.
@@ -322,7 +317,8 @@ The *name* property is a string field, and is intended to hold a *name* for a ca
 
 .. profiles_to_recipes
 
-**Renaming “Profiles” to “Recipes” to represent standard categorical variants templates**
+Renaming “Profiles” to “Recipes” to represent standard categorical variants templates
+=====================================================================================
 
 **Decision:**
 :ref:`recipes` were originally called Profiles, but the group decided to change the name to the current Recipes.
@@ -340,7 +336,8 @@ The term `profile is already used within the Variant Annotation Specification (V
 
 .. function_variants_mullers_morphs
 
-**Handling of Function Variants using Müller's Morphs**
+Handling of Function Variants using Müller's Morphs
+===================================================
 
 **Decision:**
 The classification of functional impact on protein structure in the FunctionConstraint was standardized using terms like hypermorphic, amorphic, neomorphic, and antimorphic (based on `Müller’s morphs <https://en.wikipedia.org/wiki/Muller%27s_morphs>`_), rather than terms like "gain-of-function" or "loss-of-function".
@@ -351,8 +348,6 @@ This approach provides a more structured, ontology code-backed classification. A
 
 We recognize that this terminology is inconsistent with current colloquial use of gain-of-function and loss-of-function descriptors. `A Discussion <https://github.com/ga4gh/cat-vrs/discussions/54>`_ was created on the Cat-VRS GitHub repository on October 6th, 2024 to promote discussion around this design decision. This decision will further be interrogated when this constraint is nominated to Trial Use as part of a GKS review ballot.
 
-
-
 **Citations:**
 
 *  `"Terminology for function changes" GitHub Discussion <https://github.com/ga4gh/cat-vrs/discussions/23>`_
@@ -362,38 +357,32 @@ We recognize that this terminology is inconsistent with current colloquial use o
 *  `“Handling Function Variants” GitHub Issue <https://github.com/ga4gh/cat-vrs/issues/14>`_
 *  `“Generalizing Canonical allele and Categorical CNV to handle function / expression variants” GitHub Issue <https://github.com/ga4gh/cat-vrs/discussions/16>`_
 
-
-
-
-
 .. mappable_concepts_for_relations
 
-**Integration of Mappable Concepts for Variant Relations**
+Integration of Mappable Concepts for Variant Relations
+======================================================
 
 **Decision:**
 For the relations property in the DefiningAlleleConstraint and DefiningLocationConstraint, the group decided to remove the explicit enum of possible relation methods (such as translates_to and translates_from) and instead refer to the :ref:`MappableConcept` data class.
 
-
-
 **Rationale:**
 This decision was made for a number of reasons: First, it is more consistent with `DRY <https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`_ best practices to have a single mechanism to handle relations rather than repeating lists of them multiple times throughout the specification. Second, the *gks.core:MappableConcept* class is a general-purpose data structure that holds codings of a concept and maps them to codings within other systems within a standardized way. Therefore, regardless of which coded methods are used by an implementation to relate one version of a variant to another, containerizing these coded methods in the *gks.core:MappableConcept* should make them easier to map to other coding systems.
 
-
 **Citations:**
 
 *  `“Should relation or relations be renamed?” GitHub discussion <https://github.com/ga4gh/cat-vrs/discussions/100>`_
 *  `2025-02-05 meeting minutes <https://docs.google.com/document/d/1oI4ir4OzXFvhZNbMVEX-RHGAQ-d2K4lAKP-7lf-uzPc/edit?tab=t.0#heading=h.ujjbabr6rnl>`_
 
-
-
-
-
 .. Error_Handling
 
-**Error handling is intentionally unspecified and delegated to implementation.**
-Cat-VRS provides foundational data types that enable significant flexibility.  Except where required by this specification, implementations may choose whether and how to validate data.  For example, implementations MAY choose to validate that particular combinations of objects are compatible, but such validation is not required.
+Error handling is intentionally unspecified and delegated to implementation.
+============================================================================
 
+Cat-VRS provides foundational data types that enable significant flexibility.  Except where required by this specification, implementations may choose whether and how to validate data.  For example, implementations MAY choose to validate that particular combinations of objects are compatible, but such validation is not required.
 
 .. Text_Case
 
+Text casing
+===========
+
 **Cat-VRS uses** `PascalCase (a.k.a. CamelCaps) <https://simple.wikipedia.org/wiki/CamelCase>`__ **to represent compound words and** `snake_case <https://simple.wikipedia.org/wiki/Snake_case>`__ **to represent compound file names** Although the schema is currently JSON-based (which would typically use camelCase), Cat-VRS itself is intended to be neutral with respect to languages and database.

docs/source/appendices/index.rst

@@ -1,4 +1,5 @@
 .. _appendices:
+
 Appendices
 !!!!!!!!!!
 
@@ -8,3 +9,4 @@ Appendices
    maturity_model
    design_decisions
    roadmap
+   hyperintensional_catvars

docs/source/appendices/roadmap.rst

@@ -1,4 +1,5 @@
 .. _roadmap:
+
 Product Roadmap
 !!!!!!!!!!!!!!!
 

docs/source/concepts/additional.rst

@@ -0,0 +1,24 @@
+.. _additionalDataTypes:
+
+Additional Data Types
+@@@@@@@@@@@@@@@@@@@@@
+
+Below are the additional data types used by the Cat-VRS models.
+
+.. _FunctionalDomain:
+
+FunctionalDomain
+##################
+
+The FunctionalDomain class is used to populate the `functionalDomains` property within the :ref:`AdjacencyConstraint`. It is intended to represent `Functional Domains <https://fusions.cancervariants.org/en/latest/information_model.html#categorical-elements>`_ from the VICC Gene Fusion Specification.
+
+.. include:: ../def/cat-vrs/FunctionalDomain.rst
+
+.. _UnspecifiedElement:
+
+UnspecifiedElement
+##################
+
+The UnspecifiedElement class is an available item to populate the `adjoinedElements` property within the :ref:`AdjacencyConstraint`. It is intended to represent both the `Multiple Possible Gene Component <https://fusions.cancervariants.org/en/latest/nomenclature.html#multiple-possible-gene-component>`_ and `Unknown Gene Component <https://fusions.cancervariants.org/en/latest/nomenclature.html#unknown-gene-component>`_  from the VICC Gene Fusion Specification.
+
+.. include:: ../def/cat-vrs/UnspecifiedElement.rst

docs/source/concepts/imported/ConceptSet.rst

@@ -0,0 +1,6 @@
+.. _ConceptSet:
+
+ConceptSet
+!!!!!!!!!!!
+
+.. include::  ../../def/gks-core/ConceptSet.rst