What an annotator receives

An annotatable is the thing a pipeline annotates: one position, one region or one allele, on one chromosome. It is the first argument of every annotate call, and the only thing an annotator knows about the input row apart from the context the earlier annotators built.

Annotators are typed on the base class, Annotatable, rather than on a variant, because a pipeline does not only annotate variants. annotate_tabular builds a Position from a chromosome and a position column, a Region from an added end column, a VCFAllele when there are reference and alternative columns, and a CNVAllele for a large deletion or duplication. All four reach an annotator through the same interface, and an annotator that only makes sense for some of them checks the annotatable’s type — an Type — and answers the empty result for the rest.

The interval

Every annotatable spans a closed, 1-based interval [pos, pos_end], both ends inclusive: a position has pos_end == pos, and len(annotatable) is pos_end - pos + 1. An annotator that queries a score or gene models queries exactly this span. The canonical spellings are chrom, pos and pos_end — the constructor’s arguments and the keys to_dict writes — with chromosome, position and end_position as aliases.

A VCFAllele derives both its Type and its interval from the two alleles, and the docstring below states the rule. The one thing to carry away is that for a deletion or a complex allele pos_end reaches one base past the last reference base.

Serialised form

An annotatable round-trips through a string of the form TYPE(args...): repr writes it and Annotatable.from_string reads it back, dispatching on the type token to the right subclass. That is the form an annotator writes when it hands its input to an external tool one line at a time, and the form such a tool parses on the other side; demo_annotator does exactly this in both directions.

A None annotatable

An input row may have no annotatable at all — an unparsable variant, a liftover that found nothing. The pipeline passes None through, and the answer for it is every attribute set to None, never an exception. AnnotatorBase handles the None before it reaches the subclass, so an annotator built on it never sees one in _do_annotate; a batch-only annotator that overrides _do_batch_annotate is responsible for its own None entries.

API

class gain.annotation.annotatable.Annotatable(chrom: str, pos: int, pos_end: int, annotatable_type: Type)

Base class for annotatables used in annotation pipeline.

An annotatable is the thing a pipeline annotates: a position, a region or an allele on one chromosome. Every annotatable spans a closed, 1-based interval [pos, pos_end] – both ends inclusive, so a Position has pos_end == pos and len(annotatable) is pos_end - pos + 1. VCFAllele says how it derives pos_end from its alleles.

The canonical spellings are chrom, pos and pos_end – the constructor’s names and the keys to_dict() writes. chromosome, position and end_position are aliases kept for the callers that use them; each reads the same value as its twin. Equality compares the type, the chromosome and both ends.

class Type(*values)

Defines annotatable types.

static from_string(variant: str) → Type

Construct annotatable type from string argument.

property chrom: str

The chromosome name, as given at construction.

property chromosome: str

Alias of chrom.

property end_position: int

Alias of pos_end.

static from_string(value: str) → Annotatable

Deserialize an Annotatable instance from a string value.

property pos: int

The 1-based start of the interval, inclusive.

property pos_end: int

The 1-based end of the interval, inclusive.

Equal to pos for a single position; see the class docstring for the convention and VCFAllele for how an allele’s end is derived.

property position: int

Alias of pos.

abstractmethod to_dict() → dict

Serialize the annotatable to a dictionary.

static tokenize(value: str) → tuple[str, list[str]]

Split the serialized form TYPE(arg1, arg2, ...) into its parts.

Returns the type token and the list of argument tokens, with whitespace stripped from the arguments. Raises ValueError for a value that is not exactly one call-like expression. The inverse of __repr__; from_string() dispatches on the type token and the concrete classes parse the arguments.

class gain.annotation.annotatable.Position(chrom: str, pos: int)

Annotatable class representing a single position in a chromosome.

static from_string(value: str) → Position

Deserialize an Annotatable instance from a string value.

to_dict() → dict

Serialize the annotatable to a dictionary.

class gain.annotation.annotatable.Region(chrom: str, pos_begin: int, pos_end: int)

Annotatable class representing a region in a chromosome.

static from_string(value: str) → Region

Deserialize an Annotatable instance from a string value.

to_dict() → dict

Serialize the annotatable to a dictionary.

class gain.annotation.annotatable.VCFAllele(chrom: str, pos: int, ref: str, alt: str)

A small variant in VCF terms: chrom, pos, ref and alt.

The alleles decide both the Annotatable.Type and the interval:

• one base to one base is a SUBSTITUTION, spanning pos alone;

• a one-base reference that the alternative extends (same first base) is a SMALL_INSERTION, spanning pos to pos + 1 – the two bases the insertion falls between;

• a reference longer than one base collapsed to its first base is a SMALL_DELETION, and any other pair is COMPLEX; both span pos to pos + len(ref).

So for a deletion or a complex allele pos_end reaches one base past the last reference base, which sits at pos + len(ref) - 1. Annotators query exactly this span.

The canonical spellings are ref and alt; reference and alternative are aliases. Equality also compares both alleles.

property alt: str

The alternative allele as written in VCF, anchor base included.

property alternative: str

Alias of alt.

static from_string(value: str) → VCFAllele

Deserialize a VCFAllele from its __repr__ form.

Accepts VCFAllele(chrom, pos, ref, alt), and the same four arguments under any small-variant type name (SUBSTITUTION, SMALL_INSERTION, SMALL_DELETION, COMPLEX). Raises ValueError for another type token or argument count. The type is re-derived from the alleles, not taken from the token.

property ref: str

The reference allele as written in VCF, anchor base included.

property reference: str

Alias of ref.

to_dict() → dict

Serialize to type, chrom, pos, ref and alt.

type is the type’s name. pos_end is not written: it is re-derived from the alleles.

class gain.annotation.annotatable.CNVAllele(chrom: str, pos_begin: int, pos_end: int, cnv_type: Type)

Defines copy number variants annotatable.

static from_string(value: str) → CNVAllele

Deserialize an Annotatable instance from a string value.

to_dict() → dict

Serialize the annotatable to a dictionary.