Skip to content

HGVS Models

Public Python data model for parsed HGVS variants.

The package is split into:

  • tinyhgvs.models.core for reference, coordinate-system, location, and certainty models
  • tinyhgvs.models.allele for allele and allele-form models
  • tinyhgvs.models.cdna for coding-DNA outcome models
  • tinyhgvs.models.nucleotide for nucleotide coordinates, edits, and variants
  • tinyhgvs.models.rna for RNA outcome models
  • tinyhgvs.models.repeat for repeat units and quantities
  • tinyhgvs.models.protein for protein coordinates, edits, and outcomes

Internal description aliases in this module are used for annotations only.

HgvsVariant dataclass 

HgvsVariant(reference: ReferenceSpec | None, coordinate_system: CoordinateSystem, description: _VariantDescription)

Top-level model describing a parsed HGVS variant.

This is the root object returned by tinyhgvs.parse_hgvs. It ties the reference field, coordinate system, and parsed variant description together.

Attributes:

Name Type Description
reference ReferenceSpec | None

Reference sequence field preceding the : when present.
coordinate_system CoordinateSystem

HGVS coordinate type.
description _VariantDescription

Model describing a nucleotide or protein variant.

Examples:

A coding DNA splice-site substitution parsed into reference, location, and edit models:

>>> from tinyhgvs import parse_hgvs
>>> variant = parse_hgvs("NM_004006.2:c.357+1G>A")
>>> variant.reference.primary.id
'NM_004006.2'
>>> variant.coordinate_system.value
'c'
>>> variant_description = variant.description
>>> variant_location = variant_description.location
>>> variant_location.start.coordinate
357
>>> variant_location.start.offset
1
>>> variant_location.start.anchor
<NucleotideAnchor.ABSOLUTE: 'absolute'>
>>> variant_location.end is None
True
>>> variant_description.reference
'G'
>>> variant_description.alternate
'A'

A 5' UTR substitution keeps the signed coordinate from the HGVS string:

>>> utr = parse_hgvs("NM_007373.4:c.-1C>T")
>>> utr.description.location.start.coordinate
-1
>>> utr.description.location.start.is_five_prime_utr
True

A protein frameshift is still exposed through the same top-level variant container:

>>> protein = parse_hgvs("NP_0123456.1:p.Arg97ProfsTer23")
>>> protein.description.edit.is_frameshift
True
>>> protein.description.edit.to_residue
'Pro'