Adjacency Constraint

Definition and Information Model

Warning

This data class is at a draft maturity level and may change significantly in future releases. Maturity levels are described in the GKS Maturity Model.

Computational Definition

Components that define a molecular adjacency of congruent elements.

Information Model

Some AdjacencyConstraint attributes are inherited from Constraint.

Field	Flags	Type	Limits	Description
type		string	1..1	MUST be “AdjacencyConstraint”
adjoinedElements	↓	iriReference \| MappableConcept \| Location \| Terminus \| UnspecifiedElement	2..2	The elements of the adjacency.
functionalDomains	⋮	FunctionalDomain	0..m	Functional domains whose presence or absence is required to satisfy the adjacency.
linker		Sequence Expression	0..1	The sequence found between the adjoined elements.
orderKnown		boolean	1..1	When orderKnown is true, the order of adjoinedElements is assumed to denote the 5’ partner first and the 3’ partner second. If orderKnown is false, then the order of adjoinedElements assumed not in fact to be known, as in the case of a fusion where only one or both partners are known, but not their relative order. This field is redundant and may be set to true when using Sequence Locations and following the VRS 2 Adjacency model, as the order is implied by the usage of start and end on respective adjoinedElements.

Examples

The following example Categorical Variants utilize this Constraint:

A representative example of this Constraint, from BCR(ncbi:613)::ABL1(ncbi:25):

    {
      "type": "AdjacencyConstraint",
      "orderKnown": true,
      "adjoinedElements": [
        {
          "type": "MappableConcept",
          "id": "ncbi:613",
          "conceptType": "Gene",
          "name": "BCR",
          "primaryCoding": {
            "id": "ncbi:613",
            "name": "BCR",
            "system": "https://www.ncbi.nlm.nih.gov/gene",
            "code": "613",
            "iris": [
              "https://www.ncbi.nlm.nih.gov/gene/613"
            ]
          }
        },
        {
          "type": "MappableConcept",
          "id": "ncbi:25",
          "conceptType": "Gene",
          "name": "ABL1",
          "primaryCoding": {
            "id": "ncbi:25",
            "name": "ABL1",
            "system": "https://www.ncbi.nlm.nih.gov/gene",
            "code": "25",
            "iris": [
              "https://www.ncbi.nlm.nih.gov/gene/25"
            ]
          }
        }

Implementation Guidance

The Adjacency Constraint is similar to VRS’ Adjacency class, except that the adjoinedElements field supports data types in addition to iriReference and Location. Specifically:

MappableConcept to include an element that represents a Gene.
Terminus to include an element that represents the end of a molecule.
UnspecifiedElement to include an element that is otherwise unspecified. For example, if an assay is unable to determine a fusion partner.

Note

While registered implementers use MappableConcept elements to represent Genes within their usage of the Adjacency Constraint, a Mappable Concept could also be used to represent specific regions of the genome (for example, a kinase domain). However, in these circumstances, we recommend representing the region using a VRS Sequence Location, if possible.

Genes

We recommend specifying conceptType as “Gene” and using a symbol from the HUGO Gene Nomenclature Committee (HGNC) as a primaryCoding.

The Gene Normalizer is a Python package and public REST instance that can be used to obtain Codings and Concept Mappings of gene concepts based on Ensembl, NCBI Gene, HGNC, and other data sources.

VRS Sequence Locations

We recommend the following resources for constructing Sequence Location objects:

vrs-python is a Python package and reference implementation for VRS that can be used to generate VRS digests.
SeqRepo provides access to reference sequences and can be used to obtain Sequence Reference information, such as names and aliases, when constructing Sequence Reference objects directly.

Note

While neither the moleculeType nor residueAlphabet are required attributes for a Sequence Reference, we strongly recommend populating them within your implementation to clearly communicate to users what type of sequence your SequenceReference exists upon. Consider the following values, depending on the type of SequenceReference expressed:

Sequence reference type	moleculeType	residueAlphabet
Genomic	genomic	na
RNA	RNA	na
mRNA	mRNA	na
Protein	protein	aa

For additional Implementation Guidance, please visit VRS’ page for the Sequence Location concept.