welcome to the Cat-VRS

README.md

@@ -1,3 +1,5 @@
 # Cat-VRS
 A terminology and data model for describing categorical variation concepts, built on top of the 
-[GA4GH Variation Representation Specification (VRS)](https://vrs.ga4gh.org).
+[GA4GH Variation Representation Specification (VRS)](https://vrs.ga4gh.org).
+
+![image](docs/source/images/Cat-VRS.png)

docs/source/conf.py

@@ -33,8 +33,8 @@ def _parse_release_as_version(rls):
 
 # -- Project information -----------------------------------------------------
 
-project = 'GA4GH VRSATILE'
-copyright = '2021, GA4GH VRSATILE Contributors'
+project = 'GA4GH Categorical Variation Representation Specification'
+copyright = '2023, GA4GH CatVar Study Group'
 author = 'Committers'
 master_doc = 'index'
 # N.B. RTD ignores these values. :-/
@@ -75,17 +75,15 @@ def _parse_release_as_version(rls):
 html_theme = 'sphinx_rtd_theme'
 html_logo = 'images/GA-logo.png'
 
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-html_context = {
-    'css_files': [
-        '_static/theme_overrides.css',  # override wide tables in RTD theme
-        ],
-     }
+html_css_files = ['theme_overrides.css']
 
 # Sidebars
 
-html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }
+html_sidebars = { '**': ['globaltoc.html', 'relations.html',
+                         'sourcelink.html', 'searchbox.html'] }

docs/source/defs

@@ -1 +1 @@
-../../schema/defs
+../../schema/defs/catvars/

docs/source/index.rst

@@ -1,31 +1,77 @@
-GA4GH VRSATILE
-!!!!!!!!!!!!!!
-
-.. note::
-
-   VRSATILE is a Driver Project initiative to guide extending VRS in practical,
-   real-world data exchange. **The contents of this resource are not a GA4GH
-   standard**. As the demonstrated utility of VRSATILE specification components
-   become clear through Driver Project feedback and adoption, we will advance those
-   components as proposed standards.
-
-**VRS Added Tools for Interoperable Loquacious Exchange (VRSATILE;
-prounounced "versatile")** is a set of proposed extensions for
-|vrs| to enable interoperable exchange of common descriptive data alongside
-variation concepts. Common examples of this are reference sequence ids,
-`HGVS`_ descriptors, associated concept ids, and community aliases such as
-*EGFR vIII*. VRSATILE and its components are in a draft state and a reflection
-of current Driver Project interoperability efforts based on the VRS standard.
-
-VRSATILE also enables precise representation of "aggregate" variation concepts
-(categorical variation) that bundle multiple contextual forms defined by shared
-properties. Examples of categorical variation include the concepts represented by
-`ClinVar`_ variation IDs, `CIViC`_ variation IDs, `ClinGen Allele Registry`_
-Canonical Allele IDs, and `dbSNP`_ Reference SNP IDs.
-
-.. toctree::
-   :maxdepth: 2
-   :includehidden:
-
-   value_object_descriptor/index
-   catvars/index
+Categorical Variation Representation Specification
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+To facilitate search of biomolecular variation, contemporary biomolecular
+knowledgebases routinely "flatten" variation concepts to a specific context that
+facilitates computable matching to assayed variation, and typically provide related
+contexts to help characterize the intended biological concept. For example, the
+variant "BRAF V600E" at the `CIViC`_ resource describes a protein
+change, but is flattened to a *representative genomic change* (GRCh37 chr7:g.140453136A>T)
+and contextualized with corresponding transcript (NM_004333.4:c.1799T>A) and protein
+(NP_004324.2:p.Val600Glu) descriptions. The representative change is linked to its
+ClinGen Allele Registry identifier (CAID; `CA123643`_) to facilitate CAID matching
+from ClinGen resources.
+
+However, CA123643 is likewise a collection of variation contexts, including many
+contexts that would typically not be considered equivalent to BRAF V600E:
+ENST00000497784.1:n.1834T>A, ENST00000647434.1:n.738-3918T>A, and ENST00000642228.1:c.*877T>A,
+for example, are all associated contexts with CA123643 but none result in an altered
+protein product. Similarly, `CA16602531`_ can *also* serve as a linked representative
+genomic change (through NC_000007.14:g.140753335_140753336delinsTT), but again this
+concept contains several contexts describing the role of the variant that are not
+applicable to the V600E protein variation.
+
+In addition, more complex cases of variation also exist, where the closest approximation of
+a variation amounts to a simple genomic range. Examples of these types of variation include:
+`BRAF V600 mutations`_, `TP53 truncating mutations`_, `EGFR exon 19 deletions`_. The concepts
+associated with these variation (any protein mutation at a codon, any truncating mutation in
+a gene, and any in-frame deletion in an exon) are not clearly definable using a variation
+description framework such as VRS or HGVS.
+
+To address these shortfalls, we introduce the Categorical Variation Specification (Cat-VRS). Categorical Variation
+captures the semantics that are missing or implied in genomic knowledge resources, providing a framework for
+expressing how genomic knowledge may match to assayed variation. Much like the VRS objects used
+in this specification, Categorical Variation classes are designed to instantiate objects that
+are readily usable by genomic knowledge search engines.
+
+.. _CategoricalVariation:
+
+Categorical Variation
+@@@@@@@@@@@@@@@@@@@@@
+
+.. include:: defs/CategoricalVariation.rst
+
+.. _Canonical:
+
+Canonical Allele
+################
+
+.. include:: defs/CanonicalAllele.rst
+
+.. _Described:
+
+Described Variation
+###################
+
+.. include:: defs/DescribedVariation.rst
+
+.. _CatCNV:
+
+Categorical Copy Number
+#######################
+
+.. include:: defs/CategoricalCnv.rst
+
+.. _ProtConsequence:
+
+Protein Sequence Consequence
+############################
+
+.. include:: defs/ProteinSequenceConsequence.rst
+
+
+.. _CA123643: https://reg.genome.network/redmine/projects/registry/genboree_registry/by_caid?caid=CA123643
+.. _CA16602531: http://reg.clinicalgenome.org/redmine/projects/registry/genboree_registry/by_caid?caid=CA16602531
+.. _BRAF V600 mutations: https://civicdb.org/events/genes/5/summary/variants/17/summary
+.. _EGFR exon 19 deletions: https://civicdb.org/events/genes/19/summary/variants/133/summary
+.. _TP53 truncating mutations: https://civicdb.org/events/genes/45/summary/variants/223/summary

docs/source/requirements.txt

@@ -1,2 +1,3 @@
-sphinx ~= 3.5
-jinja2 == 3.0.3
+sphinx ~= 4.2
+jinja2 == 3.1.2
+sphinx-rtd-theme == 1.3.0