Taxonomy

class korus.tax.AcousticTaxonomy(name='acoustic_taxonomy', root_tag='Unknown', path=None, overwrite=False)[source]

Bases: Taxonomy

Class for managing annotation acoustic taxonomies with a nested, tree-like structure.

When annotating acoustic data, it is customary to describe sounds by their source (e.g. a killer whale) as well as their type, i.e, their aural and spectral characteristics (e.g. a tonal call).

In the AcousticTaxonomy class, the nodes of the (primary) tree are the sound sources, and nested within each of these node is a (secondary) tree of sound types.

Args:

name: str: Descriptive, short name for the taxonomy.
root_tag: str: Tag for the root node. If specified, the root node will be automatically created at initialisation.
version: int: Version number.
overwrite: bool: Whether to overwrite the file if it already exists.

ascend(source_tag, type_tag=None, include_start_node=True)[source]

Returns a python generator for ascending the taxonomy starting at @source_tag, @type_tag.

Args:

source_tag: str: Sound source tag or identifier of starting node.
type_tag: str: Sound type tag of starting node. If None or ‘%’, the generator will only iterate through the sound-source nodes.
include_start_node: bool: Whether to include the starting node. Default is True.

Yields:

source_tag, type_tag: str, str

clear_history()[source]: Overwrites Taxonomy.clear_history

create_node(tag, identifier=None, parent=None, precursor=None, inherit_types=True, **kwargs)[source]

Add a sound source to the taxonomy.

Overwrites KTree.create_node.

Sound source attributes can be specified using keyword arguments.

It is recommended to include the following attributes:

name

description

scientific_name

tsn

Args:

tag: str: Tag for the sound source.
parent: str: Parent sound source identifier or tag. The default value is None, implying ‘root’ as parent.
precursor: str, list(str): Used for tracking the ancestry of the child node. If None, the parent identifier will be used.
inherit_types: bool: Inherit sound types from parent source. Default is True.

Returns:

node: treelib.node.Node: The new node object

Raises:

AssertionError: if the taxonomy already contains a sound source with the specified tag

create_sound_source(tag, parent=None, precursor=None, inherit_types=True, **kwargs)[source]: Merely a wrapper for create_node()

create_sound_type(tag, source_tag=None, parent=None, recursive=True, **kwargs)[source]

Add a sound type to the taxonomy.

Note that the sound type must be associated with a particular sound source, i.e., a particular node in the primary tree (which can be the root node).

Also, note that if @recursive is set to true, all child nodes (sound sources) will inherit the sound type.

Keyword arguments can be used to specify additional data to be associated with the sound type, e.g., a wordy description of its acoustic characteristics.

Args:

tag: str: Tag for the sound type. Must be unique within the sound source.
source_tag: str: Tag of the sound source that the sound type is to be associated with.
parent: str: Tag or identifier of the parent sound type. Use this to create a hierarchy of sound types.
recursive: bool: Also add this sound type to all descendant sound sources. Default is True.

property created_nodes: Overwrites KTree.created_nodes

descend(source_tag, type_tag=None, include_start_node=True)[source]

Returns a python generator for descending the taxonomy starting at @source_tag, @type_tag.

Args:

source_tag: str: Sound source tag or identifier of starting node.
type_tag: str: Sound type tag of starting node. If None or ‘%’, the generator will only iterate through the sound-source nodes.
include_start_node: bool: Whether to include the starting node. Default is True.

Yields:

source_tag, type_tag: str, str

classmethod from_dict(input_dict, path=None)[source]

Load an acoustic taxonomy from a dictionary.

Overwrites Taxonomy.from_dict

Expects the dictionary to have the keys ‘name’, ‘version’, ‘tree’.

Within the dictionary, the key ‘children’ is used to designate branching points, and the key ‘data’ is used to designate any data associated with a node. The key ‘types’ is used to designate a sub-tree of sound types associated with a particular node.

Args:

input_dict: dict(): Input dictionary.
path: str: Path to a SQLite database file for storing the taxonomy.

merge_sound_sources(tag, children=None, remove=False, data_merge_fcn=None, inherit_types=True, **kwargs)[source]: Merge sound sources

merge_sound_types(tag, source_tag=None, children=None, remove=False, data_merge_fcn=None, recursive=True, **kwargs)[source]: Merge sound types

property removed_nodes: Overwrites KTree.removed_nodes

sound_types(source_tag)[source]

Returns the KTree of sound types associated with a given sound source

Args:

source_tag: str: Sound source tag

Returns:

t: korus.tree.KTree: Sound types. Returns None if the sound source does not exist.

class korus.tax.Taxonomy(name='taxonomy', root_tag='root', path=None, overwrite=False)[source]

Bases: KTree

Class for managing annotation taxonomies with a tree-like structure where every child nodes has precisely one parent node.

The Taxonomy class is derived from korus.tax.KTree, adding the following functionalities,

SQLite database storage

version tracking, including node ancestry

TODO: add assertion to check if there is an open connection to the sqlite database

Args:

name: str: Short, descriptive name for the taxonomy.
root_tag: str: Tag for the root node. If specified, the root node will be automatically created at initialisation.
path: str: Path to a SQLite database file for storing the taxonomy. If None, the path will be set to ./{@name}.sqlite.
overwrite: bool: Whether to overwrite the file if it already exists.

classmethod from_dict(input_dict, data_transform=None, path=None)[source]

Load a taxonomy from a dictionary.

Expects the dictionary to have the keys ‘name’, ‘version’, ‘tree’.

Within the dictionary, the key ‘children’ is used to designate branching points, and the key ‘data’ is used to designate any data associated with a node.

Args:

input_dict: dict(): Input dictionary.
data_transform: callable: This function gets applied to all entries in the dictionary with the key ‘data’.
path: str: Path to a SQLite database file for storing the taxonomy.

Returns:

tax: korus.tax.Taxonomy: The taxonomy

latest_version()[source]: Get the latest version number

classmethod load(path, name='taxonomy', version=None)[source]

Load an existing taxonomy from an SQLite database.

The method expects to find the table,

taxonomy(
id INTEGER NOT NULL, name TEXT NOT NULL, version TEXT, tree JSON NOT NULL, timestamp TEXT, comment TEXT, PRIMARY KEY (id), UNIQUE (name, version)

)

Args:

path: str: Path to the database file (.sqlite)
name: str: Taxonomy name.
version: int: Taxonomy version. If not specified, the latest version will be loaded.

Returns:

: korus.tax.Taxonomy: The taxonomy

save(comment=None, overwrite=False)[source]

Save the taxonomy.

The version number is automatically incremented by +1 when this method is called, unless @overwrite is set to True in which case the currently loaded version is overwritten.

Args:

comment: str: Optional field. Typically used for describing the main changes made to the taxonomy since the last version.
overwrite: bool: If True, the version no. is not incremented and instead the currently loaded version is overwritten.

to_dict()[source]

Transform the taxonomy to a dictionary.

Returns:

: dict(): The taxonomy in the form of a dictionary.