Skip to content

Allele Models

AllelePhase

Bases: str, Enum

Model describing phase between/among alleles.

Attributes:

Name Type Description
TRANS

Alleles are In-trans phase.
UNCERTAIN

Phase between/among alleles is uncertain.

Examples:

In-trans alleles:

>>> from tinyhgvs import parse_hgvs
>>> variants = parse_hgvs("NM_004006.2:c.[2376G>C];[3103del]")
>>> variants.description.phase
<AllelePhase.TRANS: 'trans'>

Uncertain phase:

>>> variant = parse_hgvs("NC_000001.11:g.123G>A(;)345del")
>>> variant.description.phase
<AllelePhase.UNCERTAIN: 'uncertain'>

In-trans protein alleles:

>>> variants = parse_hgvs("NP_003997.1:p.[Ser68Arg];[Ser68=]")
>>> variants.description.phase
<AllelePhase.TRANS: 'trans'>

Protein alleles with uncertain phase:

>>> variant = parse_hgvs("NP_003997.1:p.(Ser73Arg)(;)(Asn103del)")
>>> variant.description.phase
<AllelePhase.UNCERTAIN: 'uncertain'>

Allele dataclass 

Allele(variants: tuple[_T, ...], state_certainty: AlleleStateCertainty)

Bases: Generic[_T]

One allele carrying one or more variants in cis.

Attributes:

Name Type Description
variants tuple[_T, ...]

Variants described on the same allele and therefore treated as occurring together in cis.

Examples:

A nucleotide allele carrying multiple variants:

>>> from tinyhgvs import parse_hgvs
>>> variant = parse_hgvs("NC_000001.11:g.[123G>A;345del]")
>>> len(variant.description.allele_one.variants)
2

A protein allele carrying multiple variants together:

>>> from tinyhgvs import parse_hgvs
>>> variant = parse_hgvs("NP_003997.1:p.[Ser68Arg;Asn594del]")
>>> len(variant.description.allele_one.variants)
2

__iter__ 

__iter__() -> Iterator[_T]

Return an iterator over variants carried by an allele in order.

Returns:

Type Description
Iterator[VariantT]

Iterator over variants carried by this allele, in the order they appear in the written description.

Examples: >>> from tinyhgvs import parse_hgvs >>> allele = parse_hgvs( ... "NP_003997.1:p.[Ser68Arg;Asn594del]" ... ).description.allele_one >>> len(tuple(allele)) 2

>>> from tinyhgvs import parse_hgvs
>>> allele = parse_hgvs(
...     "NC_000001.11:g.[123G>A;345del]"
... ).description.allele_one
>>> len(tuple(allele))
2

AlleleForm

Bases: Generic[_T]

Base class for top-level allele forms.

Allele forms describe how allele-level syntax is written at the outer level. A single allele form covers ordinary allele syntax, while derived and alternative forms cover comma and ^ syntax.

Examples:

Ordinary allele syntax:

>>> from tinyhgvs import AlleleVariant, parse_hgvs
>>> desc = parse_hgvs("NM_004006.2:c.[2376G>C];[2376=]").description
>>> isinstance(desc, AlleleVariant)
True
>>> desc.is_single
True

Derived allele syntax:

>>> from tinyhgvs import DerivedAlleleForm
>>> desc = parse_hgvs("NP_003997.1:p.[Ser68Arg,Asn594del]").description
>>> isinstance(desc, DerivedAlleleForm)
True
>>> desc.is_derived
True

Alternative allele syntax:

>>> from tinyhgvs import AlternativeAlleleForm
>>> desc = parse_hgvs("NP_003997.1:p.[Ser68Arg]^[Asn594del]").description
>>> isinstance(desc, AlternativeAlleleForm)
True
>>> desc.is_alternative
True

AlleleVariant dataclass 

AlleleVariant(allele_one: Allele[_T], allele_two: Allele[_T] | None, phase: AllelePhase | None, unphased: tuple[_T, ...])

Bases: AlleleForm[_T]

Structured representation of HGVS allele variant syntax.

An allele variant may describe:

  • a single allele carrying one or more variants.
  • two alleles with an explicit phase relationship.
  • additional alleles whose relation to the established allele state is uncertain.

Attributes:

Name Type Description
allele_one Allele[_T]

First allele in the allele-variant description.
allele_two Allele[_T] | None

Second allele, if present.
phase AllelePhase | None

Phase relation between allele_one and allele_two. This is None when only one allele is described.
unphased tuple[_T, ...]

Later variants written in uncertain relation to the established allele state.

Examples:

Variants in cis on a single allele:

>>> from tinyhgvs import parse_hgvs
>>> desc = parse_hgvs("NC_000023.10:g.[30683643A>G;33038273T>G]").description
>>> desc.allele_two is None
True
>>> desc.phase is None
True
>>> len(desc.allele_one.variants)
2

Two nucleotide alleles in trans:

>>> desc = parse_hgvs("NM_004006.2:c.[2376G>C];[3103del]").description
>>> desc.allele_two is not None
True
>>> desc.phase
<AllelePhase.TRANS: 'trans'>
>>> len(desc.allele_one.variants)
1
>>> len(desc.allele_two.variants)
1

Additional alleles with uncertain phase:

>>> desc = parse_hgvs(
...     "NC_000001.11:g.[123G>A];[345del](;)789dup"
... ).description
>>> desc.phase
<AllelePhase.TRANS: 'trans'>
>>> len(desc.unphased)
1
>>> desc.unphased[0].location.start.coordinate
789

Variants in cis on a single protein allele:

>>> desc = parse_hgvs("NP_003997.1:p.[Ser68Arg;Asn594del]").description
>>> desc.allele_two is None
True
>>> desc.phase is None
True
>>> len(desc.allele_one.variants)
2

Two protein alleles in trans:

>>> desc = parse_hgvs("NP_003997.1:p.[Ser68Arg];[Ser68=]").description
>>> desc.allele_two is not None
True
>>> desc.phase
<AllelePhase.TRANS: 'trans'>
>>> len(desc.allele_one.variants)
1
>>> len(desc.allele_two.variants)
1

phased_alleles property 

phased_alleles: tuple[Allele[_T], Allele[_T]] | None

Return the established phased allele pair, if present.

Returns:

Type Description
tuple[Allele[VariantT], Allele[VariantT]] | None

The established phased allele pair as (allele_one, allele_two) when this description contains two established alleles with an explicit phase relationship; otherwise, None.
Notes

This property reports only the primary phased allele pair represented by allele_one and allele_two. Alleles in unphased are not included.

Examples:

A single allele does not establish a phased pair:

>>> from tinyhgvs import parse_hgvs
>>> desc = parse_hgvs("NC_000001.11:g.[123G>A;345del]").description
>>> desc.phased_alleles is None
True

Two alleles with established phase return a pair:

>>> desc = parse_hgvs("NM_004006.2:c.[2376G>C];[2376=]").description
>>> desc.phase
<AllelePhase.TRANS: 'trans'>
>>> pair = desc.phased_alleles
>>> pair is not None
True
>>> len(pair[0].variants), len(pair[1].variants)
(1, 1)

Two alleles with uncertain phase do not return a pair:

>>> desc = parse_hgvs("NC_000001.11:g.123G>A(;)345del").description
>>> desc.phase
<AllelePhase.UNCERTAIN: 'uncertain'>
>>> pair = desc.phased_alleles
>>> pair is None
True

Additional alleles with uncertain relation to the established pair:

>>> desc = parse_hgvs(
...     "NC_000001.11:g.[123G>A];[345del](;)789dup"
... ).description
>>> pair = desc.phased_alleles
>>> pair is not None
True
>>> len(desc.unphased)
1

Two protein alleles with known phase:

>>> desc = parse_hgvs("NP_003997.1:p.[Ser68Arg];[Ser68=]").description
>>> desc.phase
<AllelePhase.TRANS: 'trans'>
>>> pair = desc.phased_alleles
>>> pair is not None
True
>>> len(pair[0].variants), len(pair[1].variants)
(1, 1)

Two predicted protein alleles with unknown phase:

>>> desc = parse_hgvs("NP_003997.1:p.(Ser73Arg)(;)(Asn103del)").description
>>> desc.phase
<AllelePhase.UNCERTAIN: 'uncertain'>
>>> desc.phased_alleles is None
True
>>> len(desc.unphased)
0

DerivedAlleleForm dataclass 

DerivedAlleleForm(outcomes: tuple[_T, ...])

Bases: AlleleForm[_T]

Allele form for derived outcomes written with comma syntax.

Examples:

>>> from tinyhgvs import DerivedAlleleForm, parse_hgvs
>>> desc = parse_hgvs("NP_003997.1:p.[Ser68Arg,Asn594del]").description
>>> isinstance(desc, DerivedAlleleForm)
True
>>> len(desc.outcomes)
2
>>> desc.outcomes[0].edit.to
'Arg'

AlternativeAlleleForm dataclass 

AlternativeAlleleForm(alternatives: tuple[AlleleVariant[_T], ...])

Bases: AlleleForm[_T]

Allele form for alternative allele variants written with ^ syntax.

Examples:

>>> from tinyhgvs import AlternativeAlleleForm, parse_hgvs
>>> desc = parse_hgvs("NP_003997.1:p.[Ser68Arg]^[Asn594del]").description
>>> isinstance(desc, AlternativeAlleleForm)
True
>>> len(desc.alternatives)
2
>>> desc.alternatives[0].allele_one.variants[0].edit.to
'Arg'