Sequence annotation¶

`SequenceAnnotation`([sequence])	Sequence annotation: a collection of `SequenceInterval` objects (genes, mRNAs, exons, ...) stored by ID, and linked into a directed acyclic graph by their `Parent` attributes.
`SequenceInterval`([ID, seqid, source, ...])	Single annotated interval on a sequence, such as a gene, mRNA, exon or CDS.

class picea.SequenceAnnotation(sequence=None)[source]¶

Sequence annotation: a collection of SequenceInterval objects (genes, mRNAs, exons, …) stored by ID, and linked into a directed acyclic graph by their Parent attributes.

Intervals with duplicate IDs are renamed (ID_1, ID_2, …) with a warning.

Examples

>>> gff = (
...     "ctg1\t.\tgene\t1\t90\t.\t+\t.\tID=gene1\n"
...     "ctg1\t.\tmRNA\t1\t90\t.\t+\t.\tID=mRNA1;Parent=gene1\n"
... )
>>> annotation = SequenceAnnotation.from_gff(string=gff)
>>> len(annotation)
2
>>> annotation["mRNA1"].parent
['gene1']
>>> [interval.ID for interval in annotation["gene1"].children]
['mRNA1']

Parameters:: sequence (Optional[Sequence]) – Annotated sequence. If given, its annotation is set to this annotation.

property intervals¶: List of all intervals

classmethod from_gtf(filename=None, string=None, sequence=None, link_parents=True)[source]¶

Read a GTF formatted file or string. Exactly one of filename or string must be given.

GTF lines are linked by their gene_id and transcript_id attributes, and transcript lines become mRNA intervals. Genes and transcripts that have no line of their own are created, spanning all their child intervals. Other intervals get IDs based on their transcript and type, e.g. <transcript_id>.exon_0. Lines without a gene_id become intervals without parents, with IDs like repeat_region_0.

Examples

>>> gtf = (
...     'ctg1\t.\texon\t100\t200\t.\t+\t.\tgene_id "g1"; transcript_id "t1";\n'
...     'ctg1\t.\texon\t300\t400\t.\t+\t.\tgene_id "g1"; transcript_id "t1";\n'
... )
>>> annotation = SequenceAnnotation.from_gtf(string=gtf)
>>> gene = annotation["g1"]
>>> gene.start, gene.end
(100, 400)
>>> [interval.ID for interval in gene.children]
['t1', 't1.exon_0', 't1.exon_1']

Parameters:

filename (Optional[str]) – GTF filename
string (Optional[str]) – GTF formatted string
sequence (Optional[Sequence]) – Annotated sequence
link_parents (Optional[bool]) – Link parent intervals to their children, so that children works

Returns:

Sequence annotation

Return type:

SequenceAnnotation

to_gtf()[source]¶

GTF formatted string with all intervals

Returns:: GTF formatted string
Return type:: str

classmethod from_gff(filename=None, string=None, sequence=None, link_parents=True)[source]¶

Read a GFF3 formatted file or string. Exactly one of filename or string must be given. Comment lines are skipped, and reading stops at a ##FASTA line.

Parameters:

filename (Optional[str]) – GFF3 filename
string (Optional[str]) – GFF3 formatted string
sequence (Optional[Sequence]) – Annotated sequence
link_parents (bool) – Link parent intervals to their children, so that children works

Returns:

Sequence annotation

Return type:

SequenceAnnotation

to_gff()[source]¶

GFF3 formatted string with all intervals (without header lines)

Returns:: GFF3 formatted string
Return type:: str

classmethod from_json(filename=None, string=None, sequence=None)[source]¶

Read a json formatted file or string, as written by to_json(). Exactly one of filename or string must be given.

The json must be a list of interval dictionaries (see SequenceInterval.to_dict()). Each interval dictionary can have a children list with more interval dictionaries.

Parameters:

filename (Optional[str]) – json filename
string (Optional[str]) – json formatted string
sequence (Optional[Sequence]) – Annotated sequence

Returns:

Sequence annotation

Return type:

SequenceAnnotation

to_json(indent=None)[source]¶

json formatted string with a list of interval dictionaries (see SequenceInterval.to_dict())

Parameters:: indent (Optional[int]) – Indentation, passed to json.dumps()
Returns:: json formatted string
Return type:: str

add(element)¶

Add an element, stored by its ID

Parameters:: element (DAGElement) – Element to add

property elements: List[DAGElement]¶: List of all elements

filter(filter_func)¶

Filter elements in the current collection based on the output of filter_func

Parameters:: filter_func (Callable[[DAGElement], bool]) – Callable[[DagElement], bool] receives as input an element of the current collection and returns a boolean indicating whether the element should be kept (i.e. an element with a ‘True’ return value will be kept)
Returns:: DirectedAcyclicGraph subclass with unwanted elements removed
Return type:: DirectedAcyclicGraph

groupby(group_func)¶

Group elements in the current collection by calling ‘group_func’ and using the results as a dictionary key

Parameters:: group_func (Callable[[DAGElement], Hashable]) – Callable[[DagElement], Hashable] receives as input an element of the current collection and should return something that can be used as a dictionary key (i.e. it should be hashable)
Returns:: Dictionary with keys for groups and values individual DirectedAcyclicGraph subclasses
Return type:: DefaultDict[Hashable, DirectedAcyclicGraph]

pop(ID)¶

Remove an element and return it

Parameters:: ID (Hashable) – ID of the element to remove
Returns:: The removed element
Return type:: DAGElement
Raises:: KeyError – If there is no element with this ID

class picea.SequenceInterval(ID=None, seqid=None, source=None, interval_type=None, start=None, end=None, score=None, strand=None, phase=None, children=None, container=None, **kwargs)[source]¶

Single annotated interval on a sequence, such as a gene, mRNA, exon or CDS. Corresponds to one line in a GFF3 or GTF file.

The eight fixed GFF3 columns are stored as attributes (seqid, source, interval_type, start, end, score, strand, phase). Column 9 attributes are stored as additional attributes with lowercase keys (except ID) and list values, and can also be accessed by key (interval["name"]). Predefined GFF3 attributes that are not set are None.

Examples

>>> interval = SequenceInterval.from_gff_line("ctg1\t.\tgene\t1000\t9000\t.\t+\t.\tID=gene1;Name=EDEN")
>>> interval.interval_type, interval.start, interval.end, interval.strand
('gene', 1000, 9000, '+')
>>> interval.name
['EDEN']

Parameters:

ID (Optional[str]) – Unique identifier
seqid (Optional[str]) – Name of the sequence the interval is on (e.g. a chromosome)
source (Optional[str]) – Program or database that produced the interval
interval_type (Optional[str]) – Feature type, e.g. gene, mRNA, exon or CDS
start (Optional[int]) – Start position (as in GFF3: 1-based, inclusive)
end (Optional[int]) – End position (as in GFF3: 1-based, inclusive)
score (Optional[float]) – Score
strand (Optional[str]) – +, - or .
phase (Optional[str]) – Phase of CDS intervals: 0, 1, 2 or .
children (Optional[List[str]]) – IDs of child intervals
container (Optional[SequenceAnnotation]) – Annotation the interval belongs to
**kwargs – Additional attributes. parent is the list of parent interval IDs.

property parent¶: IDs of the direct parent intervals (the GFF3 Parent attribute). Can be set with a single ID or a list of IDs. See parents for all ancestors.

property gff_attributes: Dict[str, str]¶: Column 9 attributes as a dictionary, including ID and Parent. Attributes that are None are left out.

property gtf_attributes: Dict[str, str]¶

gff_attributes without ID and Parent, plus a <type>_id attribute for the interval itself if it is a gene or mRNA, and for every ancestor (e.g. transcript_id and gene_id for an exon). Intervals with multiple parents of the same type get a single <type>_id.

Type:: Attributes for GTF output

classmethod from_gtf_line(gtf_line=None, line_number=None)[source]¶

Create an interval from a single GTF line

Parameters:

gtf_line (Optional[str]) – GTF formatted line
line_number (Optional[int]) – Line number, used in error messages

Returns:

Interval

Return type:

SequenceInterval

Raises:

ValueError – If the start, end, score, strand, or phase column has an invalid value

to_gtf_line()[source]¶

GTF formatted line (without a trailing newline). The mRNA type is written as transcript.

Returns:: GTF formatted line
Return type:: str

classmethod from_gff_line(gff_line=None, line_number=None, attribute_parser=<function parse_gff_attribute_string>)[source]¶

Create an interval from a single GFF3 line. Intervals without an ID attribute get a random UUID.

Parameters:

gff_line (Optional[str]) – GFF3 formatted line
line_number (Optional[int]) – Line number, used in error messages
attribute_parser (Callable) – Function that parses column 9 into a dictionary of lists

Returns:

Interval

Return type:

SequenceInterval

Raises:

ValueError – If the line does not have 9 columns, or if the start, end, score, strand, or phase column has an invalid value

to_gff_line(trailing_newline=False)[source]¶

GFF3 formatted line

Parameters:: trailing_newline (bool) – End the line with a newline
Returns:: GFF3 formatted line
Return type:: str

classmethod from_dict(interval_dict)[source]¶

Create an interval from a dictionary, as created by to_dict()

Parameters:: interval_dict (Dict[str, Any]) – The eight fixed GFF3 fields, ID, and an attributes dictionary
Returns:: Interval
Return type:: SequenceInterval

to_dict(include_children=False)[source]¶

Dictionary with the eight fixed GFF3 fields, ID, and an attributes dictionary with all other attributes

Parameters:: include_children (bool) – Add a children list with the dictionaries of all descendant intervals
Returns:: Interval dictionary
Return type:: Dict[str, Any]

to_json(include_children=False, indent=None)[source]¶

json formatted string of to_dict()

Parameters:

include_children (bool) – Include all descendant intervals
indent (Optional[int]) – Indentation, passed to json.dumps()

Returns:

json formatted string

Return type:

str

property ID¶: Unique identifier of the element. Setting a new ID also updates the references of parent and child elements, and the key of the element in its container.

property children: DirectedAcyclicGraph¶: All descendants of this element (children, their children, etc.), as a new graph of the same type as the container

property parents: DirectedAcyclicGraph¶: All ancestors of this element (parents, their parents, etc.), as a new graph of the same type as the container