Variant Object Representation

hgvs.edit

Representation of edit operations in HGVS variants

NARefAlt and AARefAlt are abstractions of several major variant types. They are distinguished by whether the ref and alt elements of the structure. The HGVS grammar for NA and AA are subtly different (e.g., the ref AA in a protein substitution is part of the location).

class hgvs.edit.AAExt(ref, alt, aaterm=None, length=None, uncertain=False)

Bases: hgvs.edit.Edit, hgvs.edit.AAExt

type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.AAFs(ref, alt, length=None, uncertain=False)

Bases: hgvs.edit.Edit, hgvs.edit.AAFs

type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.AARefAlt(ref, alt, uncertain=False)

Bases: hgvs.edit.Edit, hgvs.edit.AARefAlt

type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.AASub(ref, alt, uncertain=False)

Bases: hgvs.edit.AARefAlt

type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.Conv(from_ac=None, from_type=None, from_pos=None, uncertain=False, edit=None)

Bases: hgvs.edit.Edit, hgvs.edit.Conv

Conversion

type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.Dup(ref=None, uncertain=False, edit=None)

Bases: hgvs.edit.Edit, hgvs.edit.Dup

seq

Deprecated; use use ref property instead instead

type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.Edit

Bases: object

class hgvs.edit.Inv(ref=None, uncertain=False, edit=None)

Bases: hgvs.edit.Edit, hgvs.edit.Inv

Inversion

ref_n

returns an integer, either from the seq instance variable if it’s a number, or None otherwise

ref_s
type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.NACopy(copy, uncertain=False)

Bases: hgvs.edit.Edit, hgvs.edit.NACopy

Represent copy number variants (Invitae-specific use)

This class is intended for Invitae use only and does not represent a standard HGVS concept. The class may be changed, moved, or removed without notice.

type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.NADupN(n, uncertain=False)

Bases: hgvs.edit.Edit, hgvs.edit.NADupN

type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.NARefAlt(ref=None, alt=None, uncertain=False, edit=None)

Bases: hgvs.edit.Edit, hgvs.edit.NARefAlt

represents substitutions, deletions, insertions, and indels.

Variables:
  • ref – reference sequence or length
  • alt – alternate sequence
  • uncertain – boolean indicating whether the variant is uncertain/undetermined
ref_n

returns an integer, either from the ref instance variable if it’s a number, or the length of ref if it’s a string, or None otherwise

>>> NARefAlt('ACGT').ref_n
4
>>> NARefAlt('7').ref_n
7
>>> NARefAlt(7).ref_n
7
ref_s

returns a string representing the ref sequence, if it is not None and smells like a sequence

>>> NARefAlt('ACGT').ref_s
u'ACGT'
>>> NARefAlt('7').ref_s
>>> NARefAlt(7).ref_s
type

return the type of this Edit

Returns:edit type (str)
class hgvs.edit.Repeat(ref=None, min=None, max=None, uncertain=False)

Bases: hgvs.edit.Edit, hgvs.edit.Repeat

seq

Deprecated; use use ref property instead instead

type

return the type of this Edit

Returns:edit type (str)

hgvs.hgvsposition

class hgvs.hgvsposition.HGVSPosition(ac, type, pos)

Bases: hgvs.hgvsposition.HGVSPosition

HGVSPosition – Represent partial HGVS tags that refer to a position without alleles

Parameters:
  • ac (str) – sequence accession
  • type (str) – type of sequence and coordinate
  • pos (str) – sequence position

hgvs.location

class hgvs.location.AAPosition(base=None, aa=None, uncertain=False)

Bases: hgvs.location.AAPosition

is_uncertain

return True if the position is marked uncertain or undefined

pos

return base, for backward compatibility

validate()

raise AssertionError if instance variables are invalid; otherwise return True

class hgvs.location.BaseOffsetPosition(base=None, offset=0, datum=0, uncertain=False)

Bases: hgvs.location.BaseOffsetPosition

Class for dealing with CDS coordinates in transcript variants.

This class models CDS positions using a base coordinate, which is measured relative to a specified datum (CDS_START or CDS_END), and an offset, which is 0 for exonic positions and non-zero for intronic positions. Positions and offsets are 1-based, with no 0, per the HGVS recommendations. (If you’re using this with UTA, be aware that UTA uses interbase coordinates.)

hgvs datum base offset meaning
r.55 SEQ_START 55 0 RNA position 55
c.55 CDS_START 55 0 CDS position 55
c.55 CDS_START 55 0 CDS position 55
c.55+1 CDS_START 55 1 intronic variant +1 from boundary
c.-55 CDS_START -55 0 5’ UTR variant, 55 nt upstream of ATG
c.1 CDS_START 1 0 start codon
c.1234 CDS_START 1234 0 stop codon (assuming CDS length is 1233)
c.*1 CDS_END 0 1 STOP + 1
c.*55 CDS_END 0 55 3’ UTR variant, 55 nt after STOP
is_uncertain

return True if the position is marked uncertain or undefined

validate()

raise AssertionError if instance variables are invalid; otherwise return True

class hgvs.location.Interval(start, end=None, uncertain=False)

Bases: hgvs.location.Interval

is_uncertain

return True if the position is marked uncertain or undefined

validate()

raise AssertionError if instance variables are invalid; otherwise return True

class hgvs.location.SimplePosition(base=None, uncertain=False)

Bases: hgvs.location.SimplePosition

is_uncertain

return True if the position is marked uncertain or undefined

validate()

raise AssertionError if instance variables are invalid; otherwise return True

hgvs.posedit

class hgvs.posedit.PosEdit(pos=None, edit=None, uncertain=False)

Bases: hgvs.posedit.PosEdit

represents a simple variant, consisting of a single position and edit pair

length_change(on_error_raise=True)

Returns the net length change for this posedit.

The method for computing the net length change depends on the type of variant (dup, del, ins, etc). The length_change method hides this complexity from callers.

Parameters:
Returns:

A signed int for the net change in length. Negative values imply net deletions, 0 implies a balanced insertion and deletion (e.g., SNV), and positive values imply a net insertion.

Raises:

HGVSUnsupportedOperationError – When determining the length for this variant type is ill-defined or unsupported.

There are many circumstances in which the net length change cannot be determined, is ill-defined, or is unsupported. In these cases, the result depends on the value of on_error_raise: when on_error_raise is True, an exception is raised; when False, the exception is caught and None is returned. Callers might wish to pass on_error_raise=False in list comprehensions to avoid dealing with exceptions.

hgvs.variant

class hgvs.variant.SequenceVariant(ac, type, posedit)

Bases: hgvs.variant.SequenceVariant

represents a basic HGVS variant. The only requirement is that each component can be stringified; for example, passing pos as either a string or an hgvs.location.CDSInterval (for example) are both intended uses