Acoustic Taxonomy

class korus.taxonomy.acoustic.AcousticTaxonomy(name='acoustic_taxonomy', root_tag='Unknown', **kwargs)

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.

property all_labels: list[tuple]

Tags and identifiers of all the nodes in the taxonomy.

Returns:

: list[tuple]

Each item is a tuple of the form (sound-source tag, sound-type tag, sound-source identifer, sound-type identifier)

ascend(source_tag, type_tag=None, include_start_node=True)

Returns a python generator for ascending the taxonomy starting at the specified node.

If the algorithm encounters an ancestral sound source the sound-type tree of which does not contain the specified sound type, it will ascend the sound-type tree of the starting node until it finds a common sound type from where it can start iterating.

Args:

source_tag: str

Sound-source tag or identifier of starting node. If None or ‘*’, an empty iterator is returned.

type_tag: str

Sound-type tag or identifier of starting node. If None or ‘*’, the generator only iterates 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

property changes

Overwrites Taxonomy.changes

clear_history()

Overwrites Taxonomy.clear_history

create_node(tag, identifier=None, parent=None, precursor=None, inherit_types=True, **kwargs)

Add a sound source to the taxonomy.

Overwrites Taxonomy.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)

Merely a wrapper for create_node()

create_sound_type(tag, source_tag=None, parent=None, recursive=True, **kwargs)

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 Taxonomy.created_nodes

descend(source_tag, type_tag=None, include_start_node=True)

Returns a python generator for descending the taxonomy starting at the specified node.

If the algorithm encounters a descendant sound source the sound-type tree of which does not contain the starting sound type, it will skip the descendant altogether.

Args:

source_tag: str

Sound-source tag or identifier of starting node.

type_tag: str

Sound-type tag or identifier 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)

Load an acoustic taxonomy from a dictionary.

Overwrites Taxonomy.from_dict

Expects the dictionary to have the keys

tree, name, version, changes, timestamp, comment, created_nodes, removed_nodes

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.

label_exists(source_tag: str, type_tag: str | None = None) → bool

Check if certain (source,type) label exists in the taxonomy.

Args:

source_tag: str

Sound-source tag or identifier of starting node.

type_tag: str

Sound-type tag or identifier of starting node.

Returns:

exists: bool

True if label exists, False otherwise.

last_common_ancestor(labels: list[tuple[str, str]])

Finds the last common ancestor of a set of labels.

Args:

labels: list[tuple[str,str]]

List of labels. Each label is a tuple of the form (sound-source tag, sound-type tag) or (sound-source identifier, sound-type identifier)

Returns:

: tuple[str, str]

The label of the last common ancestor, which may be one of the input labels

Raises:

AssertionError: if one of the labels does not exist in the taxonomy

merge_sound_sources(tag, children=None, remove=False, data_merge_fcn=None, inherit_types=True, **kwargs)

Merge sound sources

merge_sound_types(tag, source_tag=None, children=None, remove=False, data_merge_fcn=None, recursive=True, **kwargs)

Merge sound types

property removed_nodes

Overwrites Taxonomy.removed_nodes

sound_types(source_tag: str) → Taxonomy

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

Args:

source_tag: str

Sound source tag or identifier

Returns:

t: Taxonomy

Sound types. Returns None if the sound source does not exist.