diff --git a/.requirements.txt b/.requirements.txt index e573a60a..1e6ab8bf 100644 --- a/.requirements.txt +++ b/.requirements.txt @@ -3,7 +3,7 @@ jsonschema referencing ipython pyyaml -ga4gh.gks.metaschema==0.3.0b13 +ga4gh.gks.metaschema==0.3.0b14 sphinx ~= 7.2 sphinx-rtd-theme ~= 1.2 jupyterlab diff --git a/docs/source/appendices/index.rst b/docs/source/appendices/index.rst index cc4f8abc..5da710b5 100644 --- a/docs/source/appendices/index.rst +++ b/docs/source/appendices/index.rst @@ -7,7 +7,7 @@ Appendices getting_involved design_decisions development_process - mm_and_versioning + maturity_model future_plans implementations diff --git a/docs/source/appendices/maturity_model.rst b/docs/source/appendices/maturity_model.rst new file mode 100644 index 00000000..bbb98deb --- /dev/null +++ b/docs/source/appendices/maturity_model.rst @@ -0,0 +1,153 @@ +.. _maturity-model: + +GKS Maturity Model +!!!!!!!!!!!!!!!!!! + +The Genomic Knowledge Standards work stream is developing semantic data exchange +standards for federated genomic knowledge sharing. To address this, new technical +specifications are required, such as the VRS standard, which must be developed +and iterated upon through application across community implementations. This +creates a tension between the need to create products with enough stability for +initial community adoption, while ensuring that they can evolve with minimal +disruption to interoperate smoothly across a diverse set of genomic knowledge +resources. Mechanisms for communicating the stability, uptake, and development +of technical specifications are therefore of paramount importance to addressing +this balance. + +A maturity model is a useful mechanism for communicating varying stability across +product features (e.g. data classes or protocols) of a GKS standard. This is +needed to help data producers at each stage of the adoption lifecycle +decide on the appropriate time to engage and implement the standard. Product +features that have progressed through the maturity model should have an associated +progression of support from the GKS specification maintainers for message +generation, translation, and validation tooling. + +Here we define the maturity model and release process for developing and +maintaining GKS standards, with the goal of enabling timely specification +adoption by the community. + +.. figure:: ../images/adoption_lifecycle.png + :width: 800 + + The Innovation Adoption Lifecycle. + + *The Innovation Adoption Lifecycle illustrates adoption rates (y-axis) for + new technologies over time (x-axis). Innovators (leftmost on the time axis) + are among the first to adopt a new technology, and laggards (rightmost) are + among the last, reflecting the differing needs for innovation and stability + by these community groups. Adopters in every category along the innovation + adoption lifecycle benefit from communication about the maturity of technical + specification components generated by the Genomic Knowledge Standards work + stream. Communicating when a component is ready for implementation by groups + along the innovation / stability spectrum is a primary goal of the maturity + model, enabling adopters to engage at a time that is appropriate for their + organizational needs.* + +Feature Maturity levels +@@@@@@@@@@@@@@@@@@@@@@@ + +.. figure:: ../images/maturity_levels.png + :width: 800 + + Product feature maturity level criteria and commitments. + +Product feature maturity levels are to be reviewed and advanced by consensus among +defined decision-makers following Work Stream and GA4GH processes, in consultation +with the associated product group membership. Factors to be considered for product +feature maturity advancement include the criteria specified in the above table, the +degree of adoption observed in the community, feedback provided by adopters, and +availability of specification maintainers to provide the level of support required. + +Developing a Draft Product Feature +################################## + +**Decision-makers**: :ref:`feature-developers`, :ref:`product-leads` + +**Criteria**: Draft product feature development work should be based on real use +cases across multiple environments (aligned with `GA4GH Product Development 14.5`_). +Requirements may result directly from a `landscape analysis of the problem domain`_, +or may emerge in the course of technical specification development. It is expected +that the need for product features are first discussed in a community forum (e.g. +GitHub Discussions, GKS Work Stream calls). + +**Process**: Follow the GKS :ref:`development-process`. As part of this process, +it is expected that consensus among the decision-makers was reached and major design +decisions documented. Disagreements are resolved per Work Stream and GA4GH processes. + +Advancing from Draft to Trial Use +################################# + +**Decision-makers**: :ref:`feature-developers`, :ref:`product-leads`, :ref:`product-implementers` + +**Criteria**: Advancing a draft product feature to trial use should include at least two +independent product implementers that commit to supporting the draft product feature once +it has been advanced to trial use. At least one of these implementations must be open (aligned +with `GA4GH Product Development 14.8.3`_). Advancing a product feature to trial use also mandates +a minor version increment at the next release. As part of this process, it is expected that +consensus among the decision-makers was reached and major design decisions documented. Disagreement +resolution is handled per Work Stream and GA4GH processes. + +**Process**: A ballot release is created that describes draft models under evaluation for +advancement to trial use. A survey is sent to all Product Implementers that have indicated +they are implementing one or more features under evaluation for advance to Trial Use. This +survey includes: + +1. Name of Product Implementer +#. Selection of a previously described implementation +#. If (or if multiple, which) product feature(s) are suitable for advance to Trial Use +#. Comments on response (e.g. explicit endorsement or description of gaps) + +There is a minimum 1-week review period for Product Implementers to respond, though this may +be longer at the discretion of the product leads. More time for individual contributors may +be permitted on request. + +Advancing from Trial Use to Normative +##################################### + +**Decision-makers**: :ref:`feature-developers`, :ref:`product-leads`, :ref:`product-implementers`, +:ref:`ws-leads` + +**Criteria**: A normative model should have demonstrated interoperability of multiple data +generation and data consumption implementations, and should include implementations beyond +those used to advance a model to Trial Use. Advancing a product feature to normative also +mandates a minor version increment at the next release. As part of this process, it is +expected that consensus among the decision-makers was reached and major design decisions +documented. Community consultation and disagreement resolution are handled per Work Stream +and GA4GH processes. + +.. _GA4GH Product Development 14.5: https://www.ga4gh.org/our-products/development-and-approval-process/#section_5:~:text=14.5%20Development%20work%20should%20be%20based%20on%20real%20use%20cases%20across%20multiple%20environments. +.. _landscape analysis of the problem domain: https://www.ga4gh.org/our-products/development-and-approval-process/#section_4 +.. _GA4GH Product Development 14.8.3: https://www.ga4gh.org/our-products/development-and-approval-process/#section_5:~:text=14.8.3%20implementations + +Decision-maker roles +@@@@@@@@@@@@@@@@@@@@ + +A role is assumed by a person in developing GKS technical specifications and other +GA4GH products. There are several roles relevant to this document: + +.. _feature-developers: + +Feature Developers +################## +Feature developers are members of a product group assigned to implement a product feature. + +.. _product-implementers: + +Product Implementers +#################### +Representatives of teams that will develop implementations. These typically include +(but are not limited to) Driver Project representatives that have committed to developing +the product as part of the GA4GH Product Development and Approval Process. + +.. _product-leads: + +Product Leads +############# +Designated leads of a product group, who are responsible for overseeing product development. + +.. _ws-leads: + +Work Stream Leads +################# +These are domain experts assigned by the GA4GH to coordinate and lead the activities of a +GA4GH Work Stream. diff --git a/docs/source/conf.py b/docs/source/conf.py index 38c6ac79..80b9edb8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -67,6 +67,9 @@ def _parse_release_as_version(rls): todo_include_todos = True todo_emit_warnings = True +# Number figures +# numfig = True + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/source/images/adoption_lifecycle.png b/docs/source/images/adoption_lifecycle.png index 4bbeb7f4..04d9d66a 100644 Binary files a/docs/source/images/adoption_lifecycle.png and b/docs/source/images/adoption_lifecycle.png differ diff --git a/docs/source/images/maturity_levels.png b/docs/source/images/maturity_levels.png index 49fa789f..4d95dd63 100644 Binary files a/docs/source/images/maturity_levels.png and b/docs/source/images/maturity_levels.png differ diff --git a/schema/vrs/def/Adjacency.rst b/schema/vrs/def/Adjacency.rst index d792643d..e28ecf9f 100644 --- a/schema/vrs/def/Adjacency.rst +++ b/schema/vrs/def/Adjacency.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** The `Adjacency` class can represent either the termination of a sequence or the adjoining of the end of a sequence with the beginning of an adjacent sequence, potentially with an intervening linker sequence. diff --git a/schema/vrs/def/Allele.rst b/schema/vrs/def/Allele.rst index 33082077..0d0fcbed 100644 --- a/schema/vrs/def/Allele.rst +++ b/schema/vrs/def/Allele.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** The state of a molecule at a :ref:`Location`. diff --git a/schema/vrs/def/CisPhasedBlock.rst b/schema/vrs/def/CisPhasedBlock.rst index 04788f30..b4bc5d50 100644 --- a/schema/vrs/def/CisPhasedBlock.rst +++ b/schema/vrs/def/CisPhasedBlock.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** An ordered set of co-occurring :ref:`variants ` on the same molecule. diff --git a/schema/vrs/def/CopyNumberChange.rst b/schema/vrs/def/CopyNumberChange.rst index 76e7e2bc..dde5eaa9 100644 --- a/schema/vrs/def/CopyNumberChange.rst +++ b/schema/vrs/def/CopyNumberChange.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** An assessment of the copy number of a :ref:`Location` or a :ref:`Gene` within a system (e.g. genome, cell, etc.) relative to a baseline ploidy. diff --git a/schema/vrs/def/CopyNumberCount.rst b/schema/vrs/def/CopyNumberCount.rst index 073c986f..64868682 100644 --- a/schema/vrs/def/CopyNumberCount.rst +++ b/schema/vrs/def/CopyNumberCount.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** The absolute count of discrete copies of a :ref:`Location` or :ref:`Gene`, within a system (e.g. genome, cell, etc.). diff --git a/schema/vrs/def/DerivativeMolecule.rst b/schema/vrs/def/DerivativeMolecule.rst index c540f873..9548274e 100644 --- a/schema/vrs/def/DerivativeMolecule.rst +++ b/schema/vrs/def/DerivativeMolecule.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** A molecule derived from segments of multiple adjoined molecular sequences, typically resulting from structural variation. diff --git a/schema/vrs/def/Expression.rst b/schema/vrs/def/Expression.rst index 3da9a53f..f99446de 100644 --- a/schema/vrs/def/Expression.rst +++ b/schema/vrs/def/Expression.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** Representation of a variation by a specified nomenclature or syntax for a Variation object. Common examples of expressions for the description of molecular variation include the HGVS and ISCN nomenclatures. diff --git a/schema/vrs/def/LengthExpression.rst b/schema/vrs/def/LengthExpression.rst index 417f531a..de46dd53 100644 --- a/schema/vrs/def/LengthExpression.rst +++ b/schema/vrs/def/LengthExpression.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** A sequence expressed only by its length. diff --git a/schema/vrs/def/LiteralSequenceExpression.rst b/schema/vrs/def/LiteralSequenceExpression.rst index 165c33cf..35faa7a8 100644 --- a/schema/vrs/def/LiteralSequenceExpression.rst +++ b/schema/vrs/def/LiteralSequenceExpression.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** An explicit expression of a Sequence. diff --git a/schema/vrs/def/Range.rst b/schema/vrs/def/Range.rst index a6434a9c..c2f1077b 100644 --- a/schema/vrs/def/Range.rst +++ b/schema/vrs/def/Range.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** An inclusive range of values bounded by one or more integers. diff --git a/schema/vrs/def/ReferenceLengthExpression.rst b/schema/vrs/def/ReferenceLengthExpression.rst index e24f7452..f37e644e 100644 --- a/schema/vrs/def/ReferenceLengthExpression.rst +++ b/schema/vrs/def/ReferenceLengthExpression.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** An expression of a sequence that is derived from repeating a subsequence of an associated :ref:`SequenceLocation`. diff --git a/schema/vrs/def/Residue.rst b/schema/vrs/def/Residue.rst index 95ed7101..13118320 100644 --- a/schema/vrs/def/Residue.rst +++ b/schema/vrs/def/Residue.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** A character representing a specific residue (i.e., molecular species) or groupings of these ("ambiguity codes"), using `one-letter IUPAC abbreviations `_ for nucleic acids and amino acids. diff --git a/schema/vrs/def/SequenceLocation.rst b/schema/vrs/def/SequenceLocation.rst index 81cff67c..1553b499 100644 --- a/schema/vrs/def/SequenceLocation.rst +++ b/schema/vrs/def/SequenceLocation.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** A :ref:`Location` defined by an interval on a referenced :ref:`Sequence`. diff --git a/schema/vrs/def/SequenceReference.rst b/schema/vrs/def/SequenceReference.rst index 70996bd4..d896fa61 100644 --- a/schema/vrs/def/SequenceReference.rst +++ b/schema/vrs/def/SequenceReference.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** A sequence of nucleic or amino acid character codes. diff --git a/schema/vrs/def/SequenceString.rst b/schema/vrs/def/SequenceString.rst index 2c19c6a4..00e43563 100644 --- a/schema/vrs/def/SequenceString.rst +++ b/schema/vrs/def/SequenceString.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** A character string of :ref:`Residues ` that represents a biological sequence using the conventional sequence order (5’-to-3’ for nucleic acid sequences, and amino-to-carboxyl for amino acid sequences). IUPAC ambiguity codes are permitted in Sequence Strings. diff --git a/schema/vrs/def/Terminus.rst b/schema/vrs/def/Terminus.rst index 2d5b1966..530e2c58 100644 --- a/schema/vrs/def/Terminus.rst +++ b/schema/vrs/def/Terminus.rst @@ -1,3 +1,9 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** The `Terminus` data class provides a structure for describing the end (terminus) of a molecule. Structurally similar to Adjacency, but used for describing where a molecule terminates (instead of adjoining another molecule). diff --git a/schema/vrs/def/TraversalBlock.rst b/schema/vrs/def/TraversalBlock.rst index fdea3174..607ff19f 100644 --- a/schema/vrs/def/TraversalBlock.rst +++ b/schema/vrs/def/TraversalBlock.rst @@ -1,6 +1,12 @@ + +.. warning:: This data class is at a **draft** maturity level and may change + significantly in future releases. Maturity levels are described in + the :ref:`maturity-model`. + + **Computational Definition** -A component used to describe the orientation of a molecular variation within a DerivativeMolecule. +A component used to describe the orientation of applicable molecular variation within a DerivativeMolecule. **Information Model** diff --git a/schema/vrs/json/TraversalBlock b/schema/vrs/json/TraversalBlock index 598162e6..34609cc5 100644 --- a/schema/vrs/json/TraversalBlock +++ b/schema/vrs/json/TraversalBlock @@ -11,7 +11,7 @@ "orientation" ] }, - "description": "A component used to describe the orientation of a molecular variation within a DerivativeMolecule.", + "description": "A component used to describe the orientation of applicable molecular variation within a DerivativeMolecule.", "properties": { "id": { "type": "string",