core.annotation_db.BasicAnnotationDb

core.annotation_db.BasicAnnotationDb(data=None, db=None, source=':memory:')

Provides a user table for annotations. This can be merged with either the Gff or Genbank versions.

Notes

This is the default db on Sequence, SequenceCollection and Alignment

Attributes

Name	Description
describe	top level description of the annotation db
schema_version	Return the schema version of this database.

Methods

Name	Description
add_feature	adds a record to user table
biotype_counts	return counts of biological types across all tables and seqids
close	closes the db
compatible	checks whether table_names are compatible
count_distinct	return table of counts of distinct values
from_file	Load an annotation database from a file.
get_feature_children	yields children of name
get_feature_parent	yields parents of name
get_features_matching	yield essential values to create a Feature for matching records
get_records_matching	return all fields for matching records
make_indexes	adds db indexes for core attributes
num_matches	return the number of records matching condition
subset	returns a new db instance with records matching the provided conditions
to_rich_dict	returns a dict suitable for json serialisation
union	returns a new instance with merged records with other
update	update records with those from an instance of the same type
write	writes db as bytes to path

add_feature

core.annotation_db.BasicAnnotationDb.add_feature(
    seqid,
    biotype,
    name,
    spans,
    parent_id=None,
    strand=None,
    attributes=None,
    on_alignment=False,
)

adds a record to user table

Parameters

Name	Type	Description	Default
seqid	str	name of the sequence feature resides on	required
biotype	str	biological type of the record	required
name	str	the name of a record, an identifier	required
spans	list[tuple[int, int]] \| NumpyIntArrayType	this will be sorted	required
strand	str \| int \| Strand \| None	either +, -. Defaults to ‘+’	`None`
attributes	str \| None	additional attributes as a string	`None`
on_alignment	bool \| None	whether the annotation is an alignment annotation	`False`

biotype_counts

core.annotation_db.BasicAnnotationDb.biotype_counts()

return counts of biological types across all tables and seqids

close

core.annotation_db.BasicAnnotationDb.close()

closes the db

compatible

core.annotation_db.BasicAnnotationDb.compatible(other_db, symmetric=True)

checks whether table_names are compatible

Parameters

Name	Type	Description	Default
other_db	AnnotationDbABC	the other annotation db instance	required
symmetric	bool	checks only that tables of other_db equal, or are a subset, of mine	`True`

count_distinct

core.annotation_db.BasicAnnotationDb.count_distinct(
    seqid=False,
    biotype=False,
    name=False,
)

return table of counts of distinct values

Parameters

Name	Type	Description	Default
seqid	StrOrBool	if a string, selects the subset of rows matching the provided values and counts distinct values for the other fields whose value is True.	`False`
biotype	StrOrBool	if a string, selects the subset of rows matching the provided values and counts distinct values for the other fields whose value is True.	`False`
name	StrOrBool	if a string, selects the subset of rows matching the provided values and counts distinct values for the other fields whose value is True.	`False`

Returns

Name	Type	Description
	Table with columns corresponding to argument whose value was True

Examples

To compute copy number by gene name within each genome

>>> counts_table = db.count_distinct(seqid=True, biotype="gene", name=True)

from_file

core.annotation_db.BasicAnnotationDb.from_file(path)

Load an annotation database from a file.

Parameters

Name	Type	Description	Default
path	PathType	Path to the saved database file. Must have suffix matching the class’s _suffix attribute.	required

Returns

Name	Type	Description
	An instance of the annotation database class with the loaded data.

Raises

Name	Type	Description
	ValueError	If the file suffix doesn’t match the expected suffix for this class.
	OSError	If the file doesn’t exist.

get_feature_children

core.annotation_db.BasicAnnotationDb.get_feature_children(
    name,
    biotype=None,
    **kwargs,
)

yields children of name

get_feature_parent

core.annotation_db.BasicAnnotationDb.get_feature_parent(name, **kwargs)

yields parents of name

get_features_matching

core.annotation_db.BasicAnnotationDb.get_features_matching(
    biotype=None,
    seqid=None,
    name=None,
    start=None,
    stop=None,
    strand=None,
    attributes=None,
    on_alignment=None,
    allow_partial=False,
    limit=None,
)

yield essential values to create a Feature for matching records

Parameters

Name	Type	Description	Default
limit	int \| None	maximum total number of features to yield across all tables. If None, all matching features are returned. Must be positive.	`None`

get_records_matching

core.annotation_db.BasicAnnotationDb.get_records_matching(
    biotype=None,
    seqid=None,
    name=None,
    start=None,
    stop=None,
    strand=None,
    attributes=None,
    on_alignment=None,
    allow_partial=False,
    limit=None,
)

return all fields for matching records

Parameters

Name	Type	Description	Default
limit	int \| None	maximum total number of records to yield across all tables. If None, all matching records are returned. Must be positive.	`None`

make_indexes

core.annotation_db.BasicAnnotationDb.make_indexes()

adds db indexes for core attributes

num_matches

core.annotation_db.BasicAnnotationDb.num_matches(
    seqid=None,
    biotype=None,
    name=None,
    strand=None,
    attributes=None,
    on_alignment=None,
)

return the number of records matching condition

subset

core.annotation_db.BasicAnnotationDb.subset(
    source=':memory:',
    biotype=None,
    seqid=None,
    name=None,
    start=None,
    stop=None,
    strand=None,
    attributes=None,
    allow_partial=False,
)

returns a new db instance with records matching the provided conditions

to_rich_dict

core.annotation_db.BasicAnnotationDb.to_rich_dict()

returns a dict suitable for json serialisation

union

core.annotation_db.BasicAnnotationDb.union(annot_db)

returns a new instance with merged records with other

Parameters

Name	Type	Description	Default
annot_db	AnnotationDbABC	an annotation db whose schema is either a subset, or superset of self	required

Returns

Name	Type	Description
	The class whose schema contains the other

update

core.annotation_db.BasicAnnotationDb.update(annot_db, seqids=None, **kwargs)

update records with those from an instance of the same type

write

core.annotation_db.BasicAnnotationDb.write(path)

writes db as bytes to path

Parameters

Name	Type	Description	Default
path	PathType	Path to write the database. Must have suffix matching the class’s _suffix attribute.	required

Raises

Name	Type	Description
	ValueError	If the file suffix doesn’t match the expected suffix for this class.