Tree

class korus.tree.KTree(root_tag='root')

Bases: Tree

KTree (Ketos-Tree) is 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:

root_tag: str

Tag for the root node. If specified, the root node will be automatically created at initialisation.

clear_history()

Clear the history of created and removed nodes.

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

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.

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()

Make a deep copy of the present instance See https://docs.python.org/2/library/copy.html

get_id(tag)

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)

Overwrites treelib.tree.Tree.get_node

Args:

n: str

Node tag or identifier

is_ancestor(ancestor, grandchild)

Overwrites treelib.tree.Tree.is_ancestor

Args:

ancestor: str

Node tag or identifier

grandchild: str

Node tag or identifier

last_common_ancestor(x)

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

link_past_node(n)

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)

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)

Overwrites treelib.tree.Tree.move_node

Args:

n: str

Node tag or identifier

remove_node(n)

Overwrites treelib.tree.Tree.remove_node

Args:

n: str

Node tag or identifier

property removed_nodes

rsearch(n, filter=None)

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)

Overwrites treelib.tree.Tree.show.

Args:

name: bool

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

korus.tree.tree_from_dict(tree, recipe, parent=None, data_transform=None)

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.KTree

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.tree.tree_to_dict(tree, nid=None, key=None, sort=True, reverse=False)

Transform a tree into a dictionary.

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

Args:

tree: korus.tree.KTree

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.