Table

class korus.taxonomy.taxonomy.Taxonomy(name: str = 'taxonomy', root_tag: str = 'root', version: int | None = None, timestamp: datetime | None = None, changes: list[str] | None = None, comment: str | None = None, created_nodes: dict | None = None, removed_nodes: dict | None = None)[source]

Bases: Tree

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

Derived from the treelib.tree.Tree class. It adds a few new features and makes a few changes:

tags are required to be unique.

UUIDs are always used as identifiers.

sibling nodes can be merged with the merge_nodes method.

the node creation/removal history (precursor/heritor) is tracked.

a root node may be automatically created at construction time.

changes must be committed before certain operations are allowed, e.g., removing or moving a newly created node.

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.

Attrs & Properties:

name: str version: int timestamp: datetime.datetime comment: str changes: list[str] created_nodes: dict

maps created_node_uuid -> (precursor_node_uuid(s), is_equivalent)

removed_nodes: dict: maps removed_node_uuid -> (inheritor_node_uuid(s), is_equivalent)

property all_labels

ascend(n, include_start_node=True)[source]

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

Args:

n: str: Node tag or identifier
include_start_node: bool: Whether to include the starting node. Default is True.

Yields:

tag: tuple[str]

property changes

clear_history()[source]: Clear the history of created and removed nodes.

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

Create a new, child node for a parent node.

Node attributes can be specified using keyword arguments.

Args:

tag: str: Child node tag.
identifier: str: Child node identifier. If absent, a UUID will be generated automatically.
parent: str: Parent node identifier or tag. The default value is None, implying ‘root’ as parent.
precursor: tuple: (IDs, is_equivalent) tuple, used for tracking the ancestry of the child node. If None, the parent identifier will be used.
log: bool: If True (default), add a node-created message to the _changes attr
load: bool: Always set to True when loading from a dict. If False, the _create_nodes attrs gets updated.

Returns:

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

Raises:

AssertionError: if the tree already contains a node with the specified tag

property created_nodes

deepcopy()[source]: Make a deep copy of the present instance See https://docs.python.org/2/library/copy.html

descend(n, include_start_node=True)[source]

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

Args:

n: str: Node tag or identifier.
include_start_node: bool: Whether to include the starting node. Default is True.

Yields:

tag: tuple[str]

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

Load a taxonomy from a dictionary.

Expects the dictionary to have the keys,

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

Within the ‘tree’ 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’.

Returns:

tax: korus.taxonomy.Taxonomy: The taxonomy

get_id(tag)[source]

Filters the tree nodes based on their tags.

Note: If a valid identifier is specified as input, it will be returned unchanged.

Args:

tag: str,int,list,tuple: The selected tag(s)

Returns:

ids: str,list: The corresponding node identifier(s).

get_node(n)[source]

Overwrites treelib.tree.Tree.get_node

Args:

n: str: Node tag or identifier

is_ancestor(ancestor, grandchild)[source]

Overwrites treelib.tree.Tree.is_ancestor

Args:

ancestor: str: Node tag or identifier
grandchild: str: Node tag or identifier

last_common_ancestor(x)[source]

Finds the last common ancestor of a set of nodes

Args:

x: list(str): List of node tags or identifiers

Returns:

: str: The tag of the last common ancestor, which may be one of the input nodes

Raises:

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

link_past_node(n)[source]

Overwrites treelib.tree.Tree.link_past_node

Args:

n: str: Node tag or identifier

merge_nodes(tag, children=None, remove=False, data_merge_fcn=None, **kwargs)[source]

Create a new node by merging two or more existing nodes.

Only sibling nodes can be merged in this manner.

Use keyword arguments to specify attributes of the merged node.

Args:

tag: str: Tag of the new, merged node.
children: list(str): Identifiers or tags of the nodes to be merged. These will become the children nodes of the new, merged node.
remove: bool: Remove source nodes after they have been merged. Default is False.
data_merge_fcn: callable: Receives as input a list of the ‘data’ attributes of the source nodes and returns the ‘data’ attribute of the merged node.

Returns:

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

Raises:

AssertionError: if the tree already contains a node with the specified tag AssertionError: if the source nodes are not siblings

move_node(n, new_parent)[source]

Overwrites treelib.tree.Tree.move_node

Args:

n: str: Node tag or identifier

remove_node(n)[source]

Overwrites treelib.tree.Tree.remove_node

Args:

n: str: Node tag or identifier

property removed_nodes

rsearch(n, filter=None)[source]

Overwrites treelib.tree.Tree.rsearch

Args:

n: str: Node tag or identifier
filter: callable: Function of one variable to act on the Node object

show(append_name=False, **kwargs)[source]

Overwrites treelib.tree.Tree.show.

Args:

name: bool: Whether to append the node ‘name’ to the tag. Default is False.

to_dict() → dict[source]

Transform the taxonomy to a dictionary.

Returns:

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

korus.taxonomy.taxonomy.tree_from_dict(tree, recipe, parent=None, data_transform=None)[source]

Transform a dictionary into a tree.

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

Args:

tree: korus.tree.LabelTree: Parent tree to which the data will be appended. Can be an empty tree.
recipe: dict: Dictionary recipe for building the tree.
parent: str: Tag or identifier of the node within the parent tree where the data will be appended. By default parent=None implying that the data should be appended at the root level.
data_transform: callable: This function gets applied to all entries in the dictionary with the key ‘data’.

Returns:

tree: Tree: The created tree.

korus.taxonomy.taxonomy.tree_to_dict(tree, nid=None, key=None, sort=True, reverse=False)[source]

Transform a tree into a dictionary.

The key ‘children’ is used to designate branching points.

Args:

tree: korus.tree.LabelTree: Input tree.
nid: str: Only transform the part of the tree below this node. Default is root.
key: str: @key and @reverse are present to sort nodes at each level. If @key is None sorting is performed on node tag.
sort: bool: Whether to sort nodes. The default value is True.
reverse: bool: if True, reverse sorting

Returns:

tree_dict: dict(): The created dictionary.