Skip to content

Nucleotide Models

Nucleotide-focused Python model types for parsed HGVS variants.

Type Aliases:

Name Description
NucleotideSequenceItem

Tagged union for supported inserted or replacement nucleotide sequence models.
NucleotideEdit

Tagged union for supported nucleotide edit models.

NucleotideEdit module-attribute 

NucleotideEdit: TypeAlias = NucleotideNoChange | NucleotideSubstitution | NucleotideDeletion | NucleotideDuplication | NucleotideRepeat | NucleotideInsertion | NucleotideInversion | NucleotideDeletionInsertion

Tagged union for supported nucleotide edit models:

NucleotideSequenceItem module-attribute 

NucleotideSequenceItem: TypeAlias = LiteralSequence | Repeat | CopiedSequence

Tagged union for supported inserted or replacement nucleotide components:

NucleotideAnchor

Bases: str, Enum

HGVS reference point used to interpret a nucleotide position.

Attributes:

Name Type Description
ABSOLUTE

Coordinate is read directly on the named reference sequence.
RELATIVE_CDS_START

Coordinate is read relative to the CDS start site.
RELATIVE_CDS_END

Coordinate is read relative to the CDS end site.

Examples:

An intronic splice-site substitution uses direct coordinates:

>>> from tinyhgvs import parse_hgvs
>>> variant = parse_hgvs("NM_004006.2:c.357+1G>A")
>>> variant.description.location.start.anchor
<NucleotideAnchor.ABSOLUTE: 'absolute'>

A 5' UTR substitution is anchored to the CDS start:

>>> variant = parse_hgvs("NM_007373.4:c.-1C>T")
>>> variant.description.location.start.anchor
<NucleotideAnchor.RELATIVE_CDS_START: 'relative_cds_start'>

A 3' UTR substitution is anchored to the CDS end:

>>> variant = parse_hgvs("NM_001272071.2:c.*1C>T")
>>> variant.description.location.start.anchor
<NucleotideAnchor.RELATIVE_CDS_END: 'relative_cds_end'>

NucleotideCoordinate dataclass 

NucleotideCoordinate(anchor: NucleotideAnchor | None, coordinate: int | None, offset: int | None)

A nucleotide coordinate or the explicit HGVS unknown coordinate ?.

Attributes:

Name Type Description
anchor NucleotideAnchor | None

Reference point used to interpret the coordinate. None for unknown coordinates.
coordinate int | None

Primary HGVS coordinate as written. None for unknown coordinates.
offset int | None

Signed secondary displacement from the primary coordinate. None for unknown coordinates. Positive values move downstream and negative values move upstream.

Examples:

Duplication crossing an exon/intron border:

>>> from tinyhgvs import parse_hgvs
>>> variant = parse_hgvs("NC_000023.11(NM_004006.2):c.260_264+48dup")
>>> variant.description.location.start.coordinate
260
>>> variant.description.location.end.coordinate
264
>>> variant.description.location.end.offset
48

Upstream intronic substitution:

>>> variant = parse_hgvs("NG_012232.1(NM_004006.2):c.264-2A>G")
>>> variant.description.location.start.coordinate
264
>>> variant.description.location.start.offset
-2

5' UTR and 3' UTR coordinates keep their signed coordinate values:

>>> five_prime = parse_hgvs("NM_007373.4:c.-1C>T")
>>> five_prime.description.location.start.anchor
<NucleotideAnchor.RELATIVE_CDS_START: 'relative_cds_start'>
>>> five_prime.description.location.start.coordinate
-1
>>> three_prime = parse_hgvs("NM_001272071.2:c.*1C>T")
>>> three_prime.description.location.start.anchor
<NucleotideAnchor.RELATIVE_CDS_END: 'relative_cds_end'>
>>> three_prime.description.location.start.coordinate
1

Unknown coordinates are used by uncertain location syntax:

>>> variant = parse_hgvs("NC_000023.10:g.(?_32238146)_(32984039_?)del")
>>> variant.description.location.start.start.is_unknown
True
>>> variant.description.location.end.end.coordinate is None
True

is_known property 

is_known: bool

Return True when this coordinate has a known value.

is_unknown property 

is_unknown: bool

Return True when this coordinate is written as ?.

is_intronic property 

is_intronic: bool

Return True for intronic coordinates.

Examples:

>>> from tinyhgvs import parse_hgvs
>>> parse_hgvs("NM_004006.2:c.357+1G>A").description.location.start.is_intronic
True
>>> parse_hgvs("NM_001385026.1:c.-106+2T>A").description.location.start.is_intronic
True

is_cds_start_anchored property 

is_cds_start_anchored: bool

Return True when the coordinate is relative to the CDS start.

is_cds_end_anchored property 

is_cds_end_anchored: bool

Return True when the coordinate is relative to the CDS end.

is_five_prime_utr property 

is_five_prime_utr: bool

Return True for exonic positions in the 5' UTR.

Examples:

>>> from tinyhgvs import parse_hgvs
>>> position = parse_hgvs("NM_007373.4:c.-123C>T").description.location.start
>>> position.is_five_prime_utr
True
>>> position = parse_hgvs("NM_004006.2:c.76A>G").description.location.start
>>> position.is_five_prime_utr
False

is_three_prime_utr property 

is_three_prime_utr: bool

Return True for exonic positions in the 3' UTR.

Examples:

>>> from tinyhgvs import parse_hgvs
>>> position = parse_hgvs("NM_001272071.2:c.*1C>T").description.location.start
>>> position.is_three_prime_utr
True
>>> position = parse_hgvs("NM_004006.2:c.76A>G").description.location.start
>>> position.is_three_prime_utr
False

NucleotideNoChange dataclass 

NucleotideNoChange(location: Location[NucleotideCoordinate])

Nucleotide no-change edit.

Examples:

>>> from tinyhgvs import NucleotideNoChange, parse_hgvs
>>> variant = parse_hgvs("NM_004006.2:c.2376=")
>>> isinstance(variant.description, NucleotideNoChange)
True

NucleotideSubstitution dataclass 

NucleotideSubstitution(location: Location[NucleotideCoordinate], reference: str, alternate: str)

Nucleotide substitution.

Examples:

A reference base C is substituted by A:

>>> from tinyhgvs import NucleotideSubstitution, parse_hgvs
>>> variant = parse_hgvs("NC_000023.10:g.33038255C>A")
>>> isinstance(variant.description, NucleotideSubstitution)
True
>>> variant.description.reference
'C'
>>> variant.description.alternate
'A'

NucleotideDeletion dataclass 

NucleotideDeletion(location: Location[NucleotideCoordinate])

Nucleotide deletion.

Examples:

>>> from tinyhgvs import NucleotideDeletion, parse_hgvs
>>> variant = parse_hgvs("NM_004006.2:c.5697del")
>>> isinstance(variant.description, NucleotideDeletion)
True
>>> variant.description.location.start.coordinate
5697

NucleotideDuplication dataclass 

NucleotideDuplication(location: Location[NucleotideCoordinate])

Nucleotide duplication.

Examples:

>>> from tinyhgvs import NucleotideDuplication, parse_hgvs
>>> variant = parse_hgvs("NC_000001.11:g.1234_2345dup")
>>> isinstance(variant.description, NucleotideDuplication)
True
>>> variant.description.location.end.coordinate
2345

NucleotideInversion dataclass 

NucleotideInversion(location: Location[NucleotideCoordinate])

Nucleotide inversion.

Examples:

>>> from tinyhgvs import NucleotideInversion, parse_hgvs
>>> variant = parse_hgvs("NC_000023.10:g.32361330_32361333inv")
>>> isinstance(variant.description, NucleotideInversion)
True

NucleotideRepeat dataclass 

NucleotideRepeat(location: Location[NucleotideCoordinate], sequence: tuple[Repeat, ...])

Top-level nucleotide repeat edit.

Examples:

A DNA repeat variant with a literal repeat unit:

>>> from tinyhgvs import NucleotideRepeat, parse_hgvs
>>> variant = parse_hgvs("NC_000014.8:g.123CAG[23]")
>>> isinstance(variant.description, NucleotideRepeat)
True
>>> repeat = variant.description.sequence[0]
>>> repeat.unit.value
'CAG'
>>> repeat.quantity.count
23

A RNA repeat variant can be composed of consecutive repeat blocks:

>>> variant = parse_hgvs("NM_004006.3:r.456_499us[4]cag[9]gccag[3]")
>>> len(variant.description.edit.sequence)
3
>>> variant.description.edit.sequence[2].quantity.count
3

NucleotideInsertion dataclass 

NucleotideInsertion(location: Location[NucleotideCoordinate], sequence: tuple[NucleotideSequenceItem, ...])

Nucleotide insertion.

Examples:

Literal nucleotide insertion:

>>> from tinyhgvs import LiteralSequence, NucleotideInsertion, parse_hgvs
>>> variant = parse_hgvs("NC_000023.10:g.32862923_32862924insCCT")
>>> isinstance(variant.description, NucleotideInsertion)
True
>>> item = variant.description.sequence[0]
>>> isinstance(item, LiteralSequence)
True
>>> item.value
'CCT'

A composite insertion can mix literal and copied sequence:

>>> variant = parse_hgvs("LRG_199t1:c.419_420ins[T;450_470;AGGG]")
>>> len(variant.description.sequence)
3
>>> variant.description.sequence[0].value
'T'
>>> variant.description.sequence[1].is_from_same_reference
True
>>> variant.description.sequence[2].value
'AGGG'

Insertion of repeated unspecified bases uses the shared repeat model:

>>> from tinyhgvs import UnknownRepeatUnit
>>> variant = parse_hgvs("NC_000023.10:g.32717298_32717299insN[100]")
>>> repeat = variant.description.sequence[0]
>>> isinstance(repeat.unit, UnknownRepeatUnit)
True
>>> repeat.quantity.count
100

NucleotideDeletionInsertion dataclass 

NucleotideDeletionInsertion(location: Location[NucleotideCoordinate], sequence: tuple[NucleotideSequenceItem, ...])

Nucleotide deletion-insertion.

Examples:

A deleted interval is replaced by one literal sequence component:

>>> from tinyhgvs import NucleotideDeletionInsertion, parse_hgvs
>>> variant = parse_hgvs("LRG_199t1:c.850_901delinsTTCCTCGATGCCTG")
>>> isinstance(variant.description, NucleotideDeletionInsertion)
True
>>> variant.description.sequence[0].value
'TTCCTCGATGCCTG'

Replacement sequence can be copied from the same reference:

>>> variant = parse_hgvs("NC_000022.10:g.42522624_42522669delins42536337_42536382")
>>> variant.description.sequence[0].location.start.coordinate
42536337

Replacement sequence can be a repeat item:

>>> from tinyhgvs import UnknownRepeatUnit
>>> variant = parse_hgvs("NM_004006.2:c.812_829delinsN[12]")
>>> repeat = variant.description.sequence[0]
>>> isinstance(repeat.unit, UnknownRepeatUnit)
True
>>> repeat.quantity.count
12

LiteralSequence dataclass 

LiteralSequence(value: str)

Literal-base sequence component.

Examples:

>>> from tinyhgvs import LiteralSequence, parse_hgvs
>>> variant = parse_hgvs("NC_000023.10:g.32862923_32862924insCCT")
>>> item = variant.description.sequence[0]
>>> isinstance(item, LiteralSequence)
True
>>> item.value
'CCT'

CopiedSequence dataclass 

CopiedSequence(reference: ReferenceSpec | None, coordinate_system: CoordinateSystem | None, location: KnownLocation[NucleotideCoordinate], is_inverted: bool)

Copied nucleotide sequence used in an insertion or deletion-insertion.

Attributes:

Name Type Description
reference ReferenceSpec | None

Source reference when the copied sequence comes from a different accession. None means the same outer reference.
coordinate_system CoordinateSystem | None

Source coordinate system when it differs from the outer variant. None means the same outer coordinate system.
location KnownLocation[NucleotideCoordinate]

Location on the source reference.
is_inverted bool

Whether the copied sequence is inserted in reverse orientation.

Examples:

A stretch of sequence from the same transcript is inserted in reverse orientation:

>>> from tinyhgvs import CopiedSequence, parse_hgvs
>>> variant = parse_hgvs("NM_004006.2:c.849_850ins850_900inv")
>>> item = variant.description.sequence[0]
>>> isinstance(item, CopiedSequence)
True
>>> item.is_from_same_reference
True
>>> item.location.start.coordinate
850
>>> item.location.end.coordinate
900
>>> item.is_inverted
True

A copied sequence can also come from another chromosome:

>>> variant = parse_hgvs(
...     "NC_000002.11:g.47643464_47643465ins[NC_000022.10:g.35788169_35788352]"
... )
>>> item = variant.description.sequence[0]
>>> item.reference.primary.id
'NC_000022.10'
>>> item.coordinate_system
<CoordinateSystem.GENOMIC: 'g'>