Defining Allele 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 allele and its associated relationships that are congruent with member variants.

Information Model

Some DefiningAlleleConstraint attributes are inherited from Constraint.

Field	Flags	Type	Limits	Description
type		string	1..1	MUST be “DefiningAlleleConstraint”
allele		Allele \| iriReference	1..1
relations	⋮	MappableConcept	0..m	Defined relationships from which members relate to the defining allele.

Examples

The following example Categorical Variants utilize this Constraint:

A representative example of this Constraint, from NM_004958.4(MTOR):c.5992_5993del (p.Met1998fs):

    {
      "type": "DefiningAlleleConstraint",
      "allele": {
        "id": "ga4gh:VA.0TMQdMT2OBisJ9FI4tkzaBtxGB7r8FfJ",
        "type": "Allele",
        "name": "NM_004958.4:c.5992_5993del",
        "description": "VRS variation of NM_004958.4:c.5992_5993del, generated with the VICC Variation Normalizer (https://github.com/cancervariants/variation-normalization).",
        "extensions": [
          {
            "name": "clinvar vcf",
            "value": "1-11128043-CAT-C"
          }
        ],
        "digest": "0TMQdMT2OBisJ9FI4tkzaBtxGB7r8FfJ",
        "expressions": [
          {
            "syntax": "spdi",
            "value": "NC_000001.11:11128043:AT:"
          },
          {
            "syntax": "hgvs.g",
            "value": "NC_000001.11:g.11128044_11128045del"
          },
          {
            "syntax": "hgvs.c",
            "value": "NM_004958.4:c.5992_5993del"
          },
          {
            "syntax": "hgvs.p",
            "value": "NP_004949.1:p.Met1998fs"
          }
        ],
        "location": {
          "id": "ga4gh:SL.gLe4d4Seuxn5fLCfO_2g34gF86vpGvo1",
          "description": "Coding DNA (cDNA) positions 5992 to 5993 of the MTOR MANE Select coding transcript (refseq:NM_004958.4), corresponding to genomic positions 11128044 to 11128045 on chromosome 1 (refseq:NC_000001.11, GRCh38).",
          "extensions": [
            {
              "name": "GRCh38 1-based, inclusive interval",
              "value": "chr1:11128044-11128045",
              "description": "Genomic positions 11128044 to 11128045 on chromosome 1 (refseq:NC_000001.11, GRCh38); 1-based, inclusive interval notation."
            },
            {
              "name": "GRCh38 0-based, half-open interval",
              "value": "chr1:11128043-11128045",
              "description": "Genomic positions 11128043 to 11128045 on chromosome 1 (refseq:NC_000001.11, GRCh38); 0-based, half-open interval notation."
            }
          ],
          "type": "SequenceLocation",
          "digest": "gLe4d4Seuxn5fLCfO_2g34gF86vpGvo1",
          "sequenceReference": {
            "id": "refseq:NM_004958.4",
            "name": "NM_004958.4",
            "description": "The MANE Select (GRCh38) coding transcript for MTOR.",
            "aliases": [
              "ensembl:ENST00000361445.9",
              "ga4gh:SQ.QheGYEnKbwNpM3LulbPTBQhyBSyZwuYm"
            ],
            "type": "SequenceReference",
            "refgetAccession": "SQ.QheGYEnKbwNpM3LulbPTBQhyBSyZwuYm",
            "residueAlphabet": "na"
          },
          "start": 6112,
          "end": 6114,
          "sequence": "AT"
        },
        "state": {
          "type": "ReferenceLengthExpression",
          "length": 0,
          "sequence": "",
          "repeatSubunitLength": 2
        }
      },
      "relations": [
        {
          "type": "MappableConcept",
          "primaryCoding": {
            "code": "liftover_to",
            "system": "ga4gh-gks-term:allele-relation"
          }
        },
        {
          "type": "MappableConcept",
          "primaryCoding": {
            "code": "transcribed_to",
            "system": "http://www.sequenceontology.org",
            "iris": [
              "http://www.sequenceontology.org/browser/current_release/term/transcribed_to"
            ]
          }
        }

Implementation Guidance

This Constraint is used to describe a Categorical Variant using a VRS Allele object, such as defining a Canonical Allele or Protein Sequence Consequence.

allele

The allele attribute is required and must be a valid VRS Allele object. Constructing a VRS Allele requires a Sequence Location and a sequence state.

We recommend the following resources for constructing VRS objects:

The Variation Normalizer is a Python package and public REST instance that translates plain-text HGVS expressions (for example, “NM_004333.4:c.1799T>A”) or free text natural language input (for example, “BRAF V600E”) into Normalized VRS Allele objects. The /normalize endpoint will lift genomic coordinates to the preferred GRCh38 assembly and transcripts will use the transcript selection algorithm. Additionally, HGVS Dup Del Mode will be applied for deletions and duplications represented as HGVS expressions.
vrs-python is a Python package and reference implementation for VRS that can be used to generate VRS digests for an Allele, Sequence Location, Sequence Reference, and other VRS concepts.
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 Allele exists on. Consider the following values, depending on the type of Allele expressed:

Allele type	Recipe	moleculeType	residueAlphabet
Genomic DNA	Canonical Allele	genomic	na
RNA		RNA	na
mRNA		mRNA	na
Protein	Protein Sequence Consequence	protein	aa

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 Allele.

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, depending on the Allele molecule type represented and which Recipe(s) you intend to satisfy:

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!

genomic

If you are modeling a genomic Allele, members may be the Defining Allele itself, the Defining Allele after liftover to another reference genome, an RNA or mRNA Allele transcribed from the Defining Allele, or a protein Allele that is a translation of the Defining Allele.

Coding	How the `member` relates to the Categorical Variant
ga4gh-gks-term:allele-relation:self	Use when the `member` is the Defining `Allele` itself.
ga4gh-gks-term:allele-relation:liftover_to	Use when the `member` represents the equivalent genomic DNA variant on another reference genome.
SO:transcribed_from	Use when the `member` is an RNA (pre-mRNA) or mRNA `Allele` that is transcribed from the Defining Allele.
SO:translation_of	Use when the `member` is a protein `Allele` that is a translation of the Defining Allele.

Warning

The specification currently incorrectly lists the directionality of the liftover term in the Canonical Allele Recipe.

RNA (pre-mRNA)

If you are modeling an RNA (pre-mRNA) Allele, members may be the Defining Allele itself, a projection of the Defining Allele on another RNA (pre-mRNA) transcript, a genomic Allele that is transcribed to the Defining Allele, a mRNA Allele that is processed from the Defining Allele, or a protein Allele that is a translation of the Defining Allele.

Coding	How the `member` relates to the Categorical Variant
ga4gh-gks-term:allele-relation:self	Use when the `member` is the Defining `Allele` itself.
ga4gh-gks-term:allele-relation:projection_of	Use when the `member` represents the equivalent RNA (pre-mRNA) variant on another RNA (pre-mRNA) transcript.
SO:transcribed_to	Use when the `member` is a genomic `Allele` that is transcribed to the Defining Allele.
SO:processed_from	Use when the `member` is an mRNA `Allele` that is processed from the RNA (pre-mRNA) Allele.
SO:translation_of	Use when the `member` is a protein `Allele` that is a translation of the Defining Allele.

mRNA

If you are modeling an mRNA Allele, members may be the Defining Allele itself, a projection of the Defining Allele on another mRNA transcript, a genomic Allele that is transcribed to the Defining Allele, an RNA (pre-mRNA) Allele that is processed into the Defining Allele, or a protein Allele that is a translation of the Defining Allele.

Coding	How the `member` relates to the Categorical Variant
ga4gh-gks-term:allele-relation:self	Use when the `member` is the Defining `Allele` itself.
ga4gh-gks-term:allele-relation:projection_of	Use when the `member` represents the equivalent mRNA variant on another mRNA transcript.
SO:transcribed_to	Use when the `member` is a genomic `Allele` that is transcribed to the Defining Allele.
SO:processed_into	Use when the `member` is an RNA (pre-mRNA) `Allele` that is processed into the Defining Allele.
SO:translation_of	Use when the `member` is a protein `Allele` that is a translation of the Defining Allele.

protein

If you are modeling a protein sequence Allele, members may be the Defining Allele itself, a projection of the Defining Allele on another protein isoform, a genomic Allele that is transcribed to the Defining Allele, or an RNA or mRNA Allele that translates to the Defining Allele.

Coding	How the `member` relates to the Defining Allele
ga4gh-gks-term:allele-relation:self	Use when the `member` is the Defining `Allele` itself.
ga4gh-gks-term:allele-relation:projection_of	Use when the `member` represents the equivalent protein sequence variant on another protein isoform.
SO:transcribed_to	Use when the `member` is a genomic `Allele` that is transcribed to the Defining Allele.
SO:translates_to	Use when the `member` is an RNA or mRNA `Allele` that translates to the Defining Allele.