Skip to content

4. Exploring the AlleleTranslator

There are four variant nomenclatures available in the vrs-python AlleleTranslator: SPDI, gnomad/VCF, and HGVS. In this notebook we will perform a simple Allele translation for each. We will use each of the four nomenclatures for a single variant in translating variants to VRS. his variant can be viewed in ClinVar and in gnomAD.

Step 1 - Setup Data Proxy Access

The DataProxy provides access to sequence references.

In [1]
from ga4gh.vrs.dataproxy import create_dataproxy
seqrepo_rest_service_url = "seqrepo+https://services.genomicmedlab.org/seqrepo"
seqrepo_dataproxy = create_dataproxy(uri=seqrepo_rest_service_url)

Import the AlleleTranslator class.

In [2]
from ga4gh.vrs.extras.translator import AlleleTranslator

The UTA server is required in the environment since we are translating from/to HGVS.

In [3]
import os
os.environ["UTA_DB_URL"] = "postgresql://anonymous:anonymous@uta.biocommons.org:5432/uta/uta_20241220"

From/To HGVS

This example will translate an HGVS variant to VRS using the AlleleTranslator to_vrs method.

In [4]
allele_translator = AlleleTranslator(data_proxy=seqrepo_dataproxy)
allele = allele_translator.to_vrs("NC_000005.10:g.80656489C>T", "hgvs")
allele.model_dump(exclude_none=True)

Output:

{'id': 'ga4gh:VA.ebezGL6HoAhtGJyVnB_mE5BH18ntKev4',
 'type': 'Allele',
 'digest': 'ebezGL6HoAhtGJyVnB_mE5BH18ntKev4',
 'location': {'id': 'ga4gh:SL.JiLRuuyS5wefF_6-Vw7m3Yoqqb2YFkss',
  'type': 'SequenceLocation',
  'digest': 'JiLRuuyS5wefF_6-Vw7m3Yoqqb2YFkss',
  'sequenceReference': {'type': 'SequenceReference',
   'refgetAccession': 'SQ.aUiQCzCPZ2d0csHbMSbh2NzInhonSXwI'},
  'start': 80656488,
  'end': 80656489},
 'state': {'type': 'LiteralSequenceExpression', 'sequence': 'T'}}

The output from above is the VRS representation of the Allele. Using the AlleleTranslator from_vrs method we can get back to the HGVS representation.

In [5]
allele_translator.from_vrs(allele, "hgvs")

Output:

['NC_000005.10:g.80656489C>T']

The AlleleTranslator class by default will use "GRCh38" as the default assembly when performing translation. But the actual assembly used for translation will be inferred from the reference sequence passed as part of the HGVS variant. A specific default assembly may be specified when creating an AlleleTranslator by passing in the keyword argument "default_assembly_name" with the assembly:

AlleleTranslator(data_proxy=seqrepo_dataproxy, default_assembly_name="GRCh37")

This example is using the GRCh37 representation of the variant.

In [6]
allele = allele_translator.to_vrs("NC_000005.9:g.79952308C>T", "hgvs")
allele.model_dump(exclude_none=True)

Output:

{'id': 'ga4gh:VA.hEyB1sGiQrdrPFIq4u4CF17uAuUs2Wvx',
 'type': 'Allele',
 'digest': 'hEyB1sGiQrdrPFIq4u4CF17uAuUs2Wvx',
 'location': {'id': 'ga4gh:SL.Y-itBtqe9IwbxyL4EVZ4T_X9TUsdbJ22',
  'type': 'SequenceLocation',
  'digest': 'Y-itBtqe9IwbxyL4EVZ4T_X9TUsdbJ22',
  'sequenceReference': {'type': 'SequenceReference',
   'refgetAccession': 'SQ.vbjOdMfHJvTjK_nqvFvpaSKhZillW0SX'},
  'start': 79952307,
  'end': 79952308},
 'state': {'type': 'LiteralSequenceExpression', 'sequence': 'T'}}
In [7]
allele_translator.from_vrs(allele, "hgvs")

Output:

['NC_000005.9:g.79952308C>T']

From/To SPDI

Example of translation a SPDI representation of a variant to and from VRS.

In [8]
allele = allele_translator.to_vrs("NC_000005.10:80656488:C:T","spdi")
allele.model_dump(exclude_none=True)

Output:

{'id': 'ga4gh:VA.ebezGL6HoAhtGJyVnB_mE5BH18ntKev4',
 'type': 'Allele',
 'digest': 'ebezGL6HoAhtGJyVnB_mE5BH18ntKev4',
 'location': {'id': 'ga4gh:SL.JiLRuuyS5wefF_6-Vw7m3Yoqqb2YFkss',
  'type': 'SequenceLocation',
  'digest': 'JiLRuuyS5wefF_6-Vw7m3Yoqqb2YFkss',
  'sequenceReference': {'type': 'SequenceReference',
   'refgetAccession': 'SQ.aUiQCzCPZ2d0csHbMSbh2NzInhonSXwI'},
  'start': 80656488,
  'end': 80656489},
 'state': {'type': 'LiteralSequenceExpression', 'sequence': 'T'}}
In [9]
allele_translator.from_vrs(allele, "spdi")

Output:

['NC_000005.10:80656488:1:T']

From gnomAD style VCF

For variants represented in the gnomad nomenclature, the AlleleTranslator currently only supports to_vrs to convert to VRS. from_vrs is not yet supported.

In [11]
allele = allele_translator.to_vrs("5-80656489-C-T", "gnomad")
allele.model_dump(exclude_none=True)

Output:

{'id': 'ga4gh:VA.ebezGL6HoAhtGJyVnB_mE5BH18ntKev4',
 'type': 'Allele',
 'digest': 'ebezGL6HoAhtGJyVnB_mE5BH18ntKev4',
 'location': {'id': 'ga4gh:SL.JiLRuuyS5wefF_6-Vw7m3Yoqqb2YFkss',
  'type': 'SequenceLocation',
  'digest': 'JiLRuuyS5wefF_6-Vw7m3Yoqqb2YFkss',
  'sequenceReference': {'type': 'SequenceReference',
   'refgetAccession': 'SQ.aUiQCzCPZ2d0csHbMSbh2NzInhonSXwI'},
  'start': 80656488,
  'end': 80656489},
 'state': {'type': 'LiteralSequenceExpression', 'sequence': 'T'}}