Defining Location Constraint

Definition and Information Model

Note

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

Computational Definition

The defining location and its associated relationships that are congruent with member locations.

Information Model

Some DefiningLocationConstraint attributes are inherited from Constraint.

Field	Flags	Type	Limits	Description
type		string	1..1	MUST be “DefiningLocationConstraint”
location		Sequence Location \| iriReference	1..1
relations	⋮	MappableConcept	0..m	Defined relationships from which members relate to the defining location.
matchCharacteristic		MappableConcept	1..1	A characteristic of the location that is used to match the defining location to member locations.

Examples

The following example Categorical Variants utilize this Constraint:

A representative example of this Constraint, from GRCh38/hg38 7p22.1(chr7:5905831-6014161)x3 (copy count):

    {
      "type": "DefiningLocationConstraint",
      "location": {
        "id": "ga4gh:SL.LChpEzYZaMug85TUqJUbT4MYgVk8vuQ7",
        "description": "Genomic positions 5905831 to 6014161 on chromosome 7 (refseq:NC_000007.14, GRCh38).",
        "extensions": [
          {
            "name": "GRCh38 1-based, inclusive interval",
            "value": "chr7:5905831-6014161",
            "description": "Genomic positions 5905831 to 6014161 on chromosome 7 (refseq:NC_000007.14, GRCh38); 1-based, inclusive interval notation."
          },
          {
            "name": "GRCh38 0-based, half-open interval",
            "value": "chr7:5905830-6014161",
            "description": "Genomic positions 5905830 to 6014161 on chromosome 7 (refseq:NC_000007.14, GRCh38); 0-based, half-open interval notation."
          }
        ],
        "type": "SequenceLocation",
        "digest": "LChpEzYZaMug85TUqJUbT4MYgVk8vuQ7",
        "sequenceReference": {
          "id": "refseq:NC_000007.14",
          "name": "NC_000007.14",
          "description": "Reference sequence for GRCh38 chromosome 7.",
          "aliases": [
            "GRCh38:7",
            "GRCh38:chr7",
            "ga4gh:SQ.F-LrLMe1SRpfUZHkQmvkVKFEGaoDeHul"
          ],
          "type": "SequenceReference",
          "refgetAccession": "SQ.F-LrLMe1SRpfUZHkQmvkVKFEGaoDeHul",
          "residueAlphabet": "na"
        },
        "start": [
          null,
          5905830
        ],
        "end": [
          6014161,
          null
        ]
      },
      "relations": [
        {
          "type": "MappableConcept",
          "primaryCoding": {
            "code": "liftover_to",
            "system": "ga4gh-gks-term:allele-relation"
          }
        }
      ],
      "matchCharacteristic": {
        "type": "MappableConcept",
        "primaryCoding": {
          "code": "is_within",
          "system": "ga4gh-gks-term:location-match"
        }

Implementation Guidance

This Constraint is used to describe a Categorical Variant using a VRS Sequence Location object, such as defining a specific exon or genomic segment.

location

The location attribute is required and must be a valid VRS Sequence Location.

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.

relations

The relations attribute is optional and is a MappableConcept, meaning that it should be represented using a term from a defined ontology. Relation terms describe how members of a Categorical Variant relate to the Defining Sequence Location.

Note

Specific relations may be required to satisfy certain Recipes; currently the Canonical Allele, Categorical CNV, and Protein Sequence Consequence.

The following relation terms are some to consider using with this Constraint:

Warning

Some terms use the system ga4gh-gks-term. This is an internally controlled vocabulary used specifically within the Categorical Variant Representation Specification. We may add more terms in the future. If you would like to recommend a new term, please open a Discussion to suggest one!

Coding	How the `member` relates to the Categorical Variant
ga4gh-gks-term:allele-relation:self	Use when the `member` is the Defining `Sequence Location` itself.
ga4gh-gks-term:allele-relation:liftover_to	Use when the `member` represents the equivalent genomic Sequence Location on another reference genome.
ga4gh-gks-term:allele-relation:projection_of	Use when the `member` represents the equivalent RNA (pre-mRNA), mRNA, or protein Sequence Location on another transcript or protein isoform.

matchCharacteristic

The matchCharacteristic attribute is required within a Defining Location Constraint and is a MappableConcept, meaning that it should be represented using a term from an ontology. This attribute describes how a member’s Sequence Location must relate to the Defining Sequence Location in order to satisfy the constraint.

Note

matchCharacteristics are definitional and thus do alter the scope of the Categorical Variant’s definition. In other words, they do restrict which variants satisfy the Categorical Variant’s constraints.

Warning

Some terms use the system ga4gh-gks-term. This is an internally controlled vocabulary used specifically within the Categorical Variant Representation Specification. We may add more terms in the future. If you would like to recommend a new term, please open a Discussion to suggest one!

Coding	Rationale
ga4gh-gks-term:location-match:is_within	Used when the `member`’s `Sequence Location` is entirely within the Defining `Sequence Location` . A narrow match.