Canonical Allele

Definition and Information Model

Trial Use

May change in future releases. See Maturity Model.

Computational Definition

A canonical allele is defined by an Allele that is representative of a collection of congruent Alleles, each of which depict the same nucleic acid on different underlying reference sequences. Congruent representations of an Allele often exist across different genome assemblies and associated cDNA transcript representations.

Information Model

Field	Flags	Type	Limits	Description
id		string	0..1	The ‘logical’ identifier of the Entity in the system of record, e.g. a UUID. This ‘id’ is unique within a given system, but may or may not be globally unique outside the system. It is used within a system to reference an object from another.
type		string	1..1	MUST be “CategoricalVariant”
name		string	1..1	A primary name for the entity.
description		string	0..1	A free-text description of the Entity.
aliases	⋮	string	0..m	Alternative name(s) for the Entity.
extensions	⋮	Extension	0..m	A list of extensions to the Entity, that allow for capture of information not directly supported by elements defined in the model.
members	⋮	Variation | iriReference	0..m	A non-exhaustive list of VRS Variations that satisfy the constraints of this categorical variant.
constraints	⋮	Defining Allele Constraint	1..1
mappings	⋮	ConceptMapping	0..m	A list of mappings to concepts in terminologies or code systems. Each mapping should include a coding and a relation.

Composes: Categorical Variant

A CanonicalAllele is a Categorical Variant with exactly one constraint:

1. A Defining Allele Constraint with the relations array containing both liftover_to and transcribed_to codes. This constraint MUST refer to a genomic variant for the allele.

Examples

The following example Categorical Variants satisfy this Recipe:

• NM_004958.4(MTOR):c.5992_5993del (p.Met1998fs)

• NC_000001.11:g.1699974C>G

Implementation Guidance

Constraints

Categorical Variants that are intended to represent Canonical Alleles must only contain the Defining Allele Constraint, with an Allele on a genomic Sequence Reference and the following required codings specified as relations:

Warning

Some terms use the system ga4gh-gkm-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!

Code	System	Rationale
liftover_to	ga4gh-gkm-term:allele-relation:allele-relation	To specify that VRS Alleles that are listed as members may be a liftover of the Defining Allele.
transcribed_to	http://www.sequenceontology.org	To specify that VRS Alleles that are listed as members may be transcribed from the Defining Allele.

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 for the Defining Allele that is intended to be represented as a Canonical Allele:

Sequence reference type	moleculeType	residueAlphabet
Genomic	genomic	na

Members

When modeling a Canonical Allele, members may be populated with VRS Allele objects that are:

• The Defining Allele itself

• A liftover of the Defining Allele on another reference genome

• An RNA (pre-mRNA) or mRNA Allele transcribed from the Defining Allele

• A protein Allele that is a translation of the Defining Allele.

As is the case with constructing VRS Allele objects for the Defining Allele, we recommend the Variation Normalizer, vrs-python, and SeqRepo as resources for constructing VRS Allele objects. Likewise, we recommend populating both the moleculeType and residueAlphabet attributes of the Sequence Reference for any Allele listed as a member.

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.