Taxonomy Manager

class korus.taxonomy.manager.AcousticTaxonomyManager[source]: Bases: TaxonomyManager

class korus.taxonomy.manager.TaxonomyManager(tax: Taxonomy, labels: LabelManager)[source]

Bases: object

Class for managing evolving taxonomies.

Args:

tax: korus.taxonomy.Taxonomy: The initial draft. Can be empty.

Attrs:

draft: korus.taxonomy.Taxonomy: The draft taxonomy version
releases: list[korus.taxonomy.Taxonomy]: The released taxonomy versions

crosswalk(label_id: int | list[int], dst_version: int | None = None, ascend: bool = False, descend: bool = False, always_list: bool = False, equivalent_only: bool = False) → int | list[int][source]

Map a list of label IDs to another taxonomy version.

Args:

label_id: int | list[int]: Label ID(s)
dst_version: int: Destination taxonomy version. If None, crosswalk to all versions, including the source version.
ascend: bool: Also return the labels of ancestral nodes of the mapped node(s).
descend: bool: Also return the labels of descendant nodes of the mapped node(s).
equivalent_only: bool: If True, only return the mapped label IDs that are 1-to-1

Returns:

ids: int | list[int]: The mapped label ID(s).

property current: Taxonomy: The current version (latest release) of the taxonomy

get_closest_relative(nid: str | tuple[str], version: int | None = None, mode: str = 'backward')[source]

Trace node history.

If node is present in the taxonomy, the node’s ID is returned.

If node is missing, the ID’s of its closest relatives are returned (precursor nodes if mode=backward and inheritor nodes if mode=forward.)

Args:

nid: str | tuple[str]

Node ID or set of node IDs

version: int

Taxonomy version

mode: str

backward/b: trace node history backwards in time (default)
forward/f: trace node history forward in time

Returns:

relatives: list[str] | list[tuple[str]]: IDs of the closest relatives
is_equivalent: bool: Whether the source node and the relative nodes may be considered equivalent.

get_inheritor_nodes(nid: str)[source]

Get inheritor node(s)

Args:

nid: str: The source node ID

Returns:

: list[str]: The IDs of the inheritor node(s)
: bool: Whether the source node and the inheritor node(s) may be considered equivalent.

get_label(id: int | list[int], always_list: bool = False)[source]: TODO: docstring

Args:

label: str | tuple | list: Sound source and sound type label(s). The character ‘*’ can be used as wildcard. For example, use (‘SRKW’,’*’) to retrieve all label IDs associated with the sound source ‘SRKW’, irrespective of sound type. Multiple source-type pairs can be specified as a list of tuples. Ignored if label_id is provided.
version: int: Taxonomy version. If None, the current release is used.
ascend: bool: Also return the labels of ancestral nodes.
descend: bool: Also return the labels of descendant nodes.
always_list: bool: Whether to always return a list. Default is False.
label_id: int | list[int]: Label IDs. If provided, the label and version arguments are ignored.

Returns:

ids: int | list[int]: Label identifier(s)

Raises:

ValueError: if the label does not exist in the taxonomy

get_precursor_nodes(nid: str)[source]

Get precursor node(s)

Args:

nid: str: The source node ID

Returns:

: list[str]: The IDs of the precursor node(s)
: bool: Whether the source node and the precursor node(s) may be considered equivalent.

get_taxonomy(version: int | None = None) → AcousticTaxonomy[source]: Get a given version of the taxonomy

release(comment: str | None = None)[source]

Release a new version of the taxonomy.

Increments the version number by +1. The current OS clock time is used to timestamp the release.

Args:

comment: str (optional): An explanatory note

property version: int: The current version number

korus.taxonomy.manager.get_label_id(label: str | tuple | list, taxonomy: Taxonomy, label_manager: LabelManager, ascend: bool = False, descend: bool = False, always_list: bool = False) → int | list[int][source]

Returns the IDs of one or several labels.

If @ascend is set to True, the function will also return the label IDs of all the ancestral nodes in the taxonomy tree. For example, if the sound source is specified as SRKW, it will return labels corresponding not only to SRKW, but also KW, Toothed, Cetacean, Mammal, Bio, and Unknown.

If @descend is set to True, the function will also return the label ids of all the descendant nodes in the taxonomy tree. For example, if the sound source is specified as SRKW, it will return labels corresponding not only to SRKW, but also J, K, and L pod.

Args:

label: str | tuple | list: Sound source and sound type label(s). The character ‘*’ can be used as wildcard. For example, use (‘SRKW’,’*’) to retrieve all label IDs associated with the sound source ‘SRKW’, irrespective of sound type. Multiple source-type pairs can be specified as a list of tuples.
taxonomy: Taxonomy: The taxonomy
label_manager: LabelManager: The label manager
ascend: bool: Also return the labels of ancestral nodes.
descend: bool: Also return the labels of descendant nodes.
always_list: bool: Whether to always return a list. Default is False.

Returns:

id: int | list[int]: Label identifier(s)

Raises:

ValueError: if the (sound-source, sound-type) label does not exist in the taxonomy