About us
Learn how GA4GH helps expand responsible genomic data use to benefit human health.
View in GitHub
Document
8 Nov 2023
Genomic Knowledge Standards (GKS) Work Stream
Categorical Variation (CatVar)
Categorical Variation (CatVar) Study Group in-progress documentation
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Categorical Variation Specification — GA4GH VRSATILE HEAD documentation</title><link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/theme_overrides.css" type="text/css" />
<link rel="canonical" href="https://vrsatile.readthedocs.io/en/latest/catvars/index.html" />
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script async="async" src="https://assets.readthedocs.org/static/javascript/readthedocs-doc-embed.js"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="prev" title="Value Object Descriptor Specification" href="../value_object_descriptor/index.html" />
<!-- RTD Extra Head -->
<link rel="stylesheet" href="https://assets.readthedocs.org/static/css/readthedocs-doc-embed.css" type="text/css" />
<script type="application/json" id="READTHEDOCS_DATA">{"ad_free": false, "api_host": "https://readthedocs.org", "build_date": "2022-04-20T18:26:35Z", "builder": "sphinx", "canonical_url": null, "commit": "76ecd6c3", "docroot": "/docs/source/", "features": {"docsearch_disabled": false}, "global_analytics_code": "UA-17997319-1", "language": "en", "page": "catvars/index", "programming_language": "words", "project": "vrsatile", "proxied_api_host": "/_", "source_suffix": ".rst", "subprojects": {}, "theme": "sphinx_rtd_theme", "user_analytics_code": "", "version": "latest"}</script>
<!--
Using this variable directly instead of using `JSON.parse` is deprecated.
The READTHEDOCS_DATA global variable will be removed in the future.
-->
<script type="text/javascript">
READTHEDOCS_DATA = JSON.parse(document.getElementById('READTHEDOCS_DATA').innerHTML);
</script>
<script type="text/javascript" src="https://assets.readthedocs.org/static/javascript/readthedocs-analytics.js" async="async"></script>
<!-- end RTD <extrahead> -->
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> GA4GH VRSATILE<img src="../_static/GA-logo.png" class="logo" alt="Logo"/>
</a>
<div class="version">
latest
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../value_object_descriptor/index.html">Value Object Descriptor Specification</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Categorical Variation Specification</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#categorical-variation">Categorical Variation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#canonical-variation">Canonical Variation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#complex-variation">Complex Variation</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">GA4GH VRSATILE</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home"></a> »</li>
<li>Categorical Variation Specification</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/ga4gh/vrsatile/blob/main/docs/source/catvars/index.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="categorical-variation-specification">
<h1>Categorical Variation Specification<a class="headerlink" href="#categorical-variation-specification" title="Permalink to this headline">¶</a></h1>
<p>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 <a class="reference external" href="https://civicdb.org/">CIViC</a> resource describes a protein
change, but is flattened to a <em>representative genomic change</em> (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; <a class="reference external" href="https://reg.genome.network/redmine/projects/registry/genboree_registry/by_caid?caid=CA123643">CA123643</a>) to facilitate CAID matching
from ClinGen resources.</p>
<p>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, <a class="reference external" href="http://reg.clinicalgenome.org/redmine/projects/registry/genboree_registry/by_caid?caid=CA16602531">CA16602531</a> can <em>also</em> 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.</p>
<p>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:
<a class="reference external" href="https://civicdb.org/events/genes/5/summary/variants/17/summary">BRAF V600 mutations</a>, <a class="reference external" href="https://civicdb.org/events/genes/45/summary/variants/223/summary">TP53 truncating mutations</a>, <a class="reference external" href="https://civicdb.org/events/genes/19/summary/variants/133/summary">EGFR exon 19 deletions</a>. 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.</p>
<p>To address these shortfalls, we introduce the Categorical Variation Specification. 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 value objects that
are readily usable by genomic knowledge search engines. Also see the <a class="reference internal" href="../value_object_descriptor/vrs_descriptors.html#categoricalvariationdescriptor"><span class="std std-ref">Categorical Variation Descriptor</span></a>
class for describing Categorical Variation under a consistent paradigm with the <a class="reference internal" href="../value_object_descriptor/index.html#valueobjectdescriptor"><span class="std std-ref">Value Object Descriptor</span></a>
class.</p>
<div class="section" id="categorical-variation">
<span id="categoricalvariation"></span><h2>Categorical Variation<a class="headerlink" href="#categorical-variation" title="Permalink to this headline">¶</a></h2>
<p><strong>Computational Definition</strong></p>
<p>A representation of a categorically-defined <a class="reference external" href="https://en.wikipedia.org/wiki/Domain_of_a_function">functional domain</a> for variation, in which individual variation instances may be members.</p>
<p><strong>Information Model</strong></p>
<table class="colwidths-auto clean-wrap docutils align-left">
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Type</p></th>
<th class="head"><p>Limits</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>_id</p></td>
<td><p>string</p></td>
<td><p>0..1</p></td>
<td><p>Categorical Variation Id. MUST be unique within document.</p></td>
</tr>
<tr class="row-odd"><td><p>type</p></td>
<td><p>string</p></td>
<td><p>1..1</p></td>
<td><p>MUST be Categorical Variation class name.</p></td>
</tr>
</tbody>
</table>
<div class="section" id="canonical-variation">
<span id="canonical"></span><h3>Canonical Variation<a class="headerlink" href="#canonical-variation" title="Permalink to this headline">¶</a></h3>
<p><strong>Computational Definition</strong></p>
<p>A categorical variation domain characterized by a representative Variation context to which members lift-over, project, translate, or otherwise directly align.</p>
<p><strong>Information Model</strong></p>
<p>Some CanonicalVariation attributes are inherited from <a class="reference internal" href="#categoricalvariation"><span class="std std-ref">Categorical Variation</span></a>.</p>
<table class="colwidths-auto clean-wrap docutils align-left">
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Type</p></th>
<th class="head"><p>Limits</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>_id</p></td>
<td><p>string</p></td>
<td><p>0..1</p></td>
<td><p>Categorical Variation Id. MUST be unique within document.</p></td>
</tr>
<tr class="row-odd"><td><p>type</p></td>
<td><p>string</p></td>
<td><p>1..1</p></td>
<td><p>MUST be “CanonicalVariation”.</p></td>
</tr>
<tr class="row-even"><td><p>variation</p></td>
<td><p><a class="reference external" href="https://raw.githubusercontent.com/ga4gh/vrs/1.2.1/schema/vrs.json#/definitions/Variation">Variation</a></p></td>
<td><p>1..1</p></td>
<td><p>The <a class="reference external" href="https://vrs.ga4gh.org/en/1.2.1/terms_and_model.html#variation">VRS Variation</a> object to which congruency must be determined.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="complex-variation">
<span id="complex"></span><h3>Complex Variation<a class="headerlink" href="#complex-variation" title="Permalink to this headline">¶</a></h3>
<p><strong>Computational Definition</strong></p>
<p>A categorical variation domain jointly characterized by two or more other categorical variation domains.</p>
<p><strong>Information Model</strong></p>
<p>Some ComplexVariation attributes are inherited from <a class="reference internal" href="#categoricalvariation"><span class="std std-ref">Categorical Variation</span></a>.</p>
<table class="colwidths-auto clean-wrap docutils align-left">
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Type</p></th>
<th class="head"><p>Limits</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>_id</p></td>
<td><p>string</p></td>
<td><p>0..1</p></td>
<td><p>Categorical Variation Id. MUST be unique within document.</p></td>
</tr>
<tr class="row-odd"><td><p>type</p></td>
<td><p>string</p></td>
<td><p>1..1</p></td>
<td><p>MUST be “ComplexVariation”.</p></td>
</tr>
<tr class="row-even"><td><p>operands</p></td>
<td><p><a class="reference internal" href="#categoricalvariation"><span class="std std-ref">Categorical Variation</span></a></p></td>
<td><p>2..m</p></td>
<td><p>The <a class="reference internal" href="#categoricalvariation"><span class="std std-ref">Categorical Variation</span></a> objects that are being evaluated collectively.</p></td>
</tr>
<tr class="row-odd"><td><p>operator</p></td>
<td><p>string</p></td>
<td><p>1..1</p></td>
<td><p>The logical operation applied to evaluating the object <em>operands</em>. MUST be “AND” or “OR”.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../value_object_descriptor/index.html" class="btn btn-neutral float-left" title="Value Object Descriptor Specification" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2021, GA4GH VRSATILE Contributors.
<span class="commit">Revision <code>76ecd6c3</code>.
</span></p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="Versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> Read the Docs</span>
v: latest
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<dl>
<dt>Versions</dt>
<dd><a href="/en/latest/">latest</a></dd>
<dd><a href="/en/troubleshooting/">troubleshooting</a></dd>
</dl>
<dl>
<dt>Downloads</dt>
</dl>
<dl>
<dt>On Read the Docs</dt>
<dd>
<a href="//readthedocs.org/projects/vrsatile/?fromdocs=vrsatile">Project Home</a>
</dd>
<dd>
<a href="//readthedocs.org/builds/vrsatile/?fromdocs=vrsatile">Builds</a>
</dd>
</dl>
</div>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>