reorganized and added class pages to RTD spec.

ga4gh · Nov 25, 2024 · bf2ea9a · bf2ea9a
1 parent 1b6104a
commit bf2ea9a
Show file tree

Hide file tree

Showing 35 changed files with 325 additions and 78 deletions.
diff --git a/docs/source/appendices/design_decisions.rst b/docs/source/appendices/design_decisions.rst
@@ -8,4 +8,37 @@ 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.
 
-Check back on this page for more content as development progresses!
+*Check back on this page for more content as development progresses!*
+
+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 individual
+JSON files for each class in the schema (|vrs_json|).
+
+Contributions to the schema MUST be written in the YAML document.
+
+General Principles
+##################
+
+* **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.
+
+* **Cat-VRS uses** `snake_case
+  <https://simple.wikipedia.org/wiki/Snake_case>`__ **to represent
+  compound words.** 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.
+
+* **Optional attributes start with an underscore.** Optional
+  attributes are not part of the value object.  Such attributes are
+  not considered when evaluating equality or creating computed
+  identifiers.
diff --git a/docs/source/appendices/faq.rst b/docs/source/appendices/faq.rst
@@ -1,10 +1,12 @@
 .. _faq:
 
-Frequently (Asked and) Answered Questions
-!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+Frequently Asked Questions
+!!!!!!!!!!!!!!!!!!!!!!!!!!
 
+How can I learn more about VRS? 
+    See |catvrs_discussion|
 
-How can I learn more about VRS? How can I get involved?
+How can I get involved?
     See :ref:`getting-involved`.
 
 
@@ -15,3 +17,6 @@ How can I learn more about VRS? How can I get involved?
 
 
 
+
+
+
diff --git a/docs/source/appendices/index.rst b/docs/source/appendices/index.rst
@@ -10,7 +10,6 @@ Appendices
 
    design_decisions
    faq
-   glossary
 
 
 

diff --git a/docs/source/concepts/catvrs_model.rst b/docs/source/concepts/catvrs_model.rst
@@ -0,0 +1,56 @@
+.. _catvrs_model:
+
+Cat-VRS Model
+@@@@@@@@@@@@@
+
+The following data types classes are used by Cat-VRS but maintained by either the VRS subgroup 
+or across the GKS Work Stream as core data classes.
+
+.. _categorical_variant:
+
+Categorical Variant
+###################
+
+The Categorical Variant class is the primary class in Cat-VRS. It
+depends on one or more Constraint elements to create a complete
+description of a categorical variant. 
+
+.. include:: ../def/cat-vrs/CategoricalVariant.rst
+
+.. _constraint:
+
+Constraint
+##########
+
+The *Constraint* class is an abstract class that is the parent of all
+other constraint classes.  A constraint is a rule or set of rules that
+must be satisfied for a CategoricalVariant to be considered valid.
+Constraint sub classes are only used in CategoricalVariant objects.
+
+.. _defining_allele_constraint:
+
+DefiningAlleleConstraint
+########################
+
+.. include:: ../def/cat-vrs/DefiningAlleleConstraint.rst
+
+.. _defining_location_constraint:
+
+DefiningLocationConstraint
+##########################
+
+.. include:: ../def/cat-vrs/DefiningLocationConstraint.rst
+
+.. _copy_count_constraint:
+
+CopyCountConstraint
+###################
+
+.. include:: ../def/cat-vrs/CopyCountConstraint.rst
+
+.. _copy_change_constraint:
+
+CopyChangeConstraint
+####################
+
+.. include:: ../def/cat-vrs/CopyChangeConstraint.rst
diff --git a/docs/source/concepts/imported/Allele.rst b/docs/source/concepts/imported/Allele.rst
@@ -0,0 +1,6 @@
+.. _Allele:
+
+Allele
+!!!!!!
+
+.. include::  ../../def/vrs/Allele.rst
diff --git a/docs/source/concepts/imported/Coding.rst b/docs/source/concepts/imported/Coding.rst
@@ -0,0 +1,6 @@
+.. _Coding:
+
+Coding
+!!!!!!
+
+.. include::  ../../def/gks-core/Coding.rst
diff --git a/docs/source/concepts/imported/ConceptMapping.rst b/docs/source/concepts/imported/ConceptMapping.rst
@@ -0,0 +1,6 @@
+.. _ConceptMapping:
+
+ConceptMapping
+!!!!!!!!!!!!!!
+
+.. include::  ../../def/gks-core/ConceptMapping.rst
diff --git a/docs/source/concepts/imported/CopyNumberChange.rst b/docs/source/concepts/imported/CopyNumberChange.rst
@@ -0,0 +1,6 @@
+.. _CopyNumberChange:
+
+Copy Number Change
+!!!!!!!!!!!!!!!!!!
+
+.. include::  ../../def/vrs/CopyNumberChange.rst
diff --git a/docs/source/concepts/imported/CopyNumberCount.rst b/docs/source/concepts/imported/CopyNumberCount.rst
@@ -0,0 +1,6 @@
+.. _CopyNumberCount:
+
+Copy Number Count
+!!!!!!!!!!!!!!!!!
+
+.. include::  ../../def/vrs/CopyNumberCount.rst
diff --git a/docs/source/concepts/imported/Element.rst b/docs/source/concepts/imported/Element.rst
@@ -0,0 +1,6 @@
+.. _Element:
+
+Element
+!!!!!!
+
+.. include::  ../../def/gks-core/Element.rst
diff --git a/docs/source/concepts/imported/Entity.rst b/docs/source/concepts/imported/Entity.rst
@@ -0,0 +1,6 @@
+.. _Entity:
+
+Entity
+!!!!!!
+
+.. include::  ../../def/gks-core/Entity.rst
diff --git a/docs/source/concepts/imported/Expression.rst b/docs/source/concepts/imported/Expression.rst
@@ -0,0 +1,6 @@
+.. _Expression:
+
+Expression
+!!!!!!!!!!
+
+.. include::  ../../def/vrs/Expression.rst
diff --git a/docs/source/concepts/imported/Extension.rst b/docs/source/concepts/imported/Extension.rst
@@ -0,0 +1,6 @@
+.. _Extension:
+
+Extension
+!!!!!!!!!
+
+.. include::  ../../def/gks-core/Extension.rst
diff --git a/docs/source/concepts/imported/Location.rst b/docs/source/concepts/imported/Location.rst
@@ -0,0 +1,6 @@
+.. _Location:
+
+Location
+!!!!!!!!
+
+.. include::  ../../def/vrs/Location.rst
diff --git a/docs/source/concepts/imported/MappableConcept.rst b/docs/source/concepts/imported/MappableConcept.rst
@@ -0,0 +1,6 @@
+.. _MappableConcept:
+
+MappableConcept
+!!!!!!!!!!!!!!!
+
+.. include::  ../../def/gks-core/MappableConcept.rst
diff --git a/docs/source/concepts/imported/Range.rst b/docs/source/concepts/imported/Range.rst
@@ -0,0 +1,6 @@
+.. _Range:
+
+Range
+!!!!!
+
+.. include::  ../../def/vrs/Range.rst
diff --git a/docs/source/concepts/imported/SequenceLocation.rst b/docs/source/concepts/imported/SequenceLocation.rst
@@ -0,0 +1,6 @@
+.. _SequenceLocation:
+
+Sequence Location
+!!!!!!!!!!!!!!!!!
+
+.. include::  ../../def/vrs/SequenceLocation.rst
diff --git a/docs/source/concepts/imported/Variation.rst b/docs/source/concepts/imported/Variation.rst
@@ -0,0 +1,6 @@
+.. _Variation:
+
+Variation
+!!!!!!!!!
+
+.. include::  ../../def/vrs/Variation.rst
diff --git a/docs/source/concepts/imported/code.rst b/docs/source/concepts/imported/code.rst
@@ -0,0 +1,6 @@
+.. _code:
+
+code
+!!!!
+
+.. include::  ../../def/gks-core/code.rst
diff --git a/docs/source/concepts/imported/index.rst b/docs/source/concepts/imported/index.rst
@@ -0,0 +1,37 @@
+.. _imported:
+
+Imported Data Types & Classes
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+The following data types classes are used by Cat-VRS but maintained by either the VRS subgroup 
+or across the GKS Work Stream as core data classes.
+
+VRS
+!!!
+
+.. toctree::
+   :titlesonly:
+
+   Variation
+   Allele
+   CopyNumberCount
+   CopyNumberChange
+   Location
+   SequenceLocation
+   Expression
+   Range
+
+GKS Core
+!!!!!!!!
+
+.. toctree::
+   :titlesonly:
+
+   Entity
+   Element
+   Extension
+   MappableConcept
+   ConceptMapping
+   Coding
+   code
+   iriReference
diff --git a/docs/source/concepts/imported/iriReference.rst b/docs/source/concepts/imported/iriReference.rst
@@ -0,0 +1,6 @@
+.. _iriReference:
+
+iriReference
+!!!!!!!!!!!!
+
+.. include::  ../../def/gks-core/iriReference.rst
diff --git a/docs/source/concepts/index.rst b/docs/source/concepts/index.rst
@@ -0,0 +1,22 @@
+Data Model
+!!!!!!!!!!
+
+At the Cat-VRS top of the Cat-VRS data model is the Categorical Variant class.
+The Categorical Variant is composed of one or more constraints that define The
+Categorical Variant. The Constraint subclasses are used to define what we refer
+to as **Recipes**. Recipes are pre-defined Categorical Variants with specific
+constraints that represent standard categorical variants that have been identified.
+The following sections describe the Cat-VRS base classes (Categorical Variant and
+Constraint subclasses), the standard recipes, and the additional *Imported* data
+class and types from VRS 2.0 and GKS Core 1.0 that support the Cat-VRS data model.
+
+- :ref:`catvrs_model`: models that describe categorical variation and constraints
+- :ref:`recipes`: models that describe categorical variation recipes with specific constraints
+- :ref:`imported`: imported data types and classes that support the above models
+
+.. toctree::
+    :hidden:
+
+    catvrs_model
+    recipes
+    imported/index
diff --git a/docs/source/concepts/recipes.rst b/docs/source/concepts/recipes.rst
@@ -0,0 +1,34 @@
+.. _recipes:
+
+Recipes
+@@@@@@@
+
+A *Recipe* is not a class. It is a term defined to differentiate between a
+specialized CategoricalVariant and a general CategoricalVariant. These
+recipes are pre-defined CategoricalVariants with specific constraints
+that represent standard categorical variants that have been identified
+in variant knowledgebases and registries. Implementers are encouraged
+to use the recipes that exist whenever possible, but are free to create
+new recipes as needed in a given implementation. New recipes should be
+shared with the community on the |catvrs_discussion| board.
+
+.. _canonical_allele:
+
+CanonicalAllele
+!!!!!!!!!!!!!!!
+
+.. include:: ../def/cat-vrs/CanonicalAllele.rst
+
+.. _categorical_cnv:
+
+CategoricalCnv
+!!!!!!!!!!!!!!
+
+.. include:: ../def/cat-vrs/CategoricalCnv.rst
+
+.. _protein_sequence_consequence:
+
+ProteinSequenceConsequence
+!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. include:: ../def/cat-vrs/ProteinSequenceConsequence.rst
diff --git a/docs/source/def-core b/docs/source/def-core
diff --git a/docs/source/def-profiles b/docs/source/def-profiles
diff --git a/docs/source/def/cat-vrs b/docs/source/def/cat-vrs
@@ -0,0 +1 @@
+../../../schema/cat-vrs/def
diff --git a/docs/source/def/gks-core b/docs/source/def/gks-core
@@ -0,0 +1 @@
+../../../schema/gks-core/def
diff --git a/docs/source/def/vrs b/docs/source/def/vrs
@@ -0,0 +1 @@
+../../../schema/vrs/def