🌱 BaseNode

bigtree.node.basenode

BaseNode

BaseNode(parent=None, children=None, **kwargs)

BaseNode extends any Python class to a tree node. Nodes can have attributes if they are initialized from Node, dictionary, or pandas DataFrame.

Nodes can be linked to each other with parent and children setter methods, or using bitshift operator with the convention parent_node >> child_node or child_node << parent_node.

Examples:

>>> from bigtree import Node, print_tree
>>> root = Node("a", age=90)
>>> b = Node("b", age=65)
>>> c = Node("c", age=60)
>>> d = Node("d", age=40)
>>> root.children = [b, c]
>>> d.parent = b
>>> print_tree(root, attr_list=["age"])
a [age=90]
├── b [age=65]
│   └── d [age=40]
└── c [age=60]

>>> from bigtree import Node
>>> root = Node("a", age=90)
>>> b = Node("b", age=65)
>>> c = Node("c", age=60)
>>> d = Node("d", age=40)
>>> root >> b
>>> root >> c
>>> d << b
>>> print_tree(root, attr_list=["age"])
a [age=90]
├── b [age=65]
│   └── d [age=40]
└── c [age=60]

Directly passing parent argument.

>>> from bigtree import Node
>>> root = Node("a")
>>> b = Node("b", parent=root)
>>> c = Node("c", parent=root)
>>> d = Node("d", parent=b)

Directly passing children argument.

>>> from bigtree import Node
>>> d = Node("d")
>>> c = Node("c")
>>> b = Node("b", children=[d])
>>> a = Node("a", children=[b, c])

BaseNode Creation

Node can be created by instantiating a BaseNode class or by using a dictionary. If node is created with dictionary, all keys of dictionary will be stored as class attributes.

>>> from bigtree import Node
>>> root = Node.from_dict({"name": "a", "age": 90})

BaseNode Attributes

These are node attributes that have getter and/or setter methods.

Get and set other BaseNode

1. parent: Get/set parent node
2. children: Get/set child nodes

Get other BaseNode

1. ancestors: Get ancestors of node excluding self, iterator
2. descendants: Get descendants of node excluding self, iterator
3. leaves: Get all leaf node(s) from self, iterator
4. siblings: Get siblings of self
5. left_sibling: Get sibling left of self
6. right_sibling: Get sibling right of self

Get BaseNode configuration

1. node_path: Get tuple of nodes from root
2. is_root: Get indicator if self is root node
3. is_leaf: Get indicator if self is leaf node
4. root: Get root node of tree
5. diameter: Get diameter of self
6. depth: Get depth of self
7. max_depth: Get maximum depth from root to leaf node

BaseNode Methods

These are methods available to be performed on BaseNode.

Constructor methods

1. from_dict(): Create BaseNode from dictionary

BaseNode methods

1. describe(): Get node information sorted by attributes, return list of tuples
2. get_attr(attr_name: str): Get value of node attribute
3. set_attrs(attrs: dict): Set node attribute name(s) and value(s)
4. go_to(node: Self): Get a path from own node to another node from same tree
5. append(node: Self): Add child to node
6. extend(nodes: list[Self]): Add multiple children to node
7. copy(): Deep copy self
8. sort(): Sort child nodes
9. plot(): Plot tree in line form
10. query(query: str): Filter tree using Tree Query Language

---

parent property writable

parent

Get parent node.

Returns:

Type	Description
T | None	Parent node, none if the node is root

parents property writable

parents

Do not allow parents attribute to be accessed.

Raises:

Type	Description
AttributeError	No such attribute

children deletable property writable

children

Get child nodes.

Returns:

Type	Description
tuple[T, ...]	Child node(s)

ancestors property

ancestors

Get iterator to yield all ancestors of self, does not include self.

Returns:

Type	Description
Iterable[T]	Ancestor(s) of node excluding itself

descendants property

descendants

Get iterator to yield all descendants of self, does not include self.

Returns:

Type	Description
Iterable[T]	Descendant(s) of node excluding itself

leaves property

leaves

Get iterator to yield all leaf nodes from self.

Returns:

Type	Description
Iterable[T]	Leaf node(s) of node

siblings property

siblings

Get siblings of self.

Returns:

Type	Description
Iterable[T]	Sibling(s) of node

left_sibling property

left_sibling

Get sibling left of self.

Returns:

Type	Description
T | None	Left sibling of node

right_sibling property

right_sibling

Get sibling right of self.

Returns:

Type	Description
T | None	Right sibling of node

node_path property

node_path

Get tuple of nodes starting from root.

Returns:

Type	Description
Iterable[T]	Node path from root to itself

is_root property

is_root

Get indicator if self is root node.

Returns:

Type	Description
bool	Indicator if node is root node

is_leaf property

is_leaf

Get indicator if self is leaf node.

Returns:

Type	Description
bool	Indicator if node is leaf node

root property

root

Get root node of tree.

Returns:

Type	Description
T	Root node

diameter property

diameter

Get diameter of tree or subtree, the length of longest path between any two nodes.

Returns:

Type	Description
int	Diameter of node

depth property

depth

Get depth of self, indexing starts from 1.

Returns:

Type	Description
int	Depth of node

max_depth property

max_depth

Get maximum depth from root to leaf node.

Returns:

Type	Description
int	Maximum depth of tree

from_dict classmethod

from_dict(input_dict)

Construct node from dictionary, all keys of dictionary will be stored as class attributes. Input dictionary must have key name if not Node will not have any name.

Examples:

>>> from bigtree import Node
>>> a = Node.from_dict({"name": "a", "age": 90})

Parameters:

Name	Type	Description	Default
input_dict	Mapping[str, Any]	node information, key: attribute name, value: attribute value	required

Returns:

Type	Description
BaseNode	Base node

describe

describe(exclude_attributes=(), exclude_prefix='')

Get node information sorted by attribute name, returns list of tuples.

Examples:

>>> from bigtree.node.node import Node
>>> a = Node('a', age=90)
>>> a.describe()
[('_BaseNode__children', []), ('_BaseNode__parent', None), ('_sep', '/'), ('age', 90), ('name', 'a')]
>>> a.describe(exclude_prefix="_")
[('age', 90), ('name', 'a')]
>>> a.describe(exclude_prefix="_", exclude_attributes=["name"])
[('age', 90)]

Parameters:

Name	Type	Description	Default
exclude_attributes	Iterable[str]	attributes to exclude	()
exclude_prefix	str	prefix of attributes to exclude	''

Returns:

Type	Description
list[tuple[str, Any]]	List of attribute name and attribute value pairs

get_attr

get_attr(attr_name, default=None)

Get value of node attribute. Returns default value if attribute name does not exist.

• Support chained attribute (e.g., parent.parent.attr_name, data.attr_name)
• Support nested attribute (e.g., children[0].attr_name)
• Support Callable that takes in the node and return the attribute value

Examples:

>>> from bigtree.node.node import Node
>>> a = Node('a', age=90)
>>> a.get_attr("age")
90

Parameters:

Name	Type	Description	Default
attr_name	str	attribute name	required
default	Any	default value if attribute does not exist	None

Returns:

Type	Description
Any	Attribute value of node

set_attrs

set_attrs(attrs)

Set node attributes.

Examples:

>>> from bigtree.node.node import Node
>>> a = Node('a')
>>> a.set_attrs({"age": 90})
>>> a
Node(/a, age=90)

Parameters:

Name	Type	Description	Default
attrs	Mapping[str, Any]	attribute information, key: attribute name, value: attribute value	required

go_to

go_to(node)

Get path from current node to specified node from same tree, uses get_path function.

Parameters:

Name	Type	Description	Default
node	T	node to travel to from current node, inclusive of start and end node	required

Returns:

Type	Description
Iterable[T]	Path from current node to destination node

append

append(other)

Add other as child of self. Can be chained.

Parameters:

Name	Type	Description	Default
other	T	other node, child to be added	required

extend

extend(others)

Add others as children of self. Can be chained.

Parameters:

Name	Type	Description	Default
others	list[T]	other nodes, children to be added	required

copy

copy()

Deep copy self; clone BaseNode.

Examples:

>>> from bigtree.node.node import Node
>>> a = Node('a')
>>> a_copy = a.copy()

Returns:

Type	Description
T	Cloned copy of node

sort

sort(**kwargs)

Sort children, possible keyword arguments include key=lambda node: node.node_name, reverse=True. Accepts kwargs for sort() function. Can be chained.

Examples:

>>> from bigtree import Node, print_tree
>>> a = Node('a')
>>> c = Node("c", parent=a)
>>> b = Node("b", parent=a)
>>> print_tree(a)
a
├── c
└── b
>>> a.sort(key=lambda node: node.node_name)
Node(/a, )
>>> print_tree(a)
a
├── b
└── c

plot

plot(*args, **kwargs)

Plot tree in line form. Accepts args and kwargs for matplotlib.pyplot.plot() function.

Examples:

>>> from bigtree import list_to_tree
>>> path_list = ["a/b/d", "a/b/e/g", "a/b/e/h", "a/c/f"]
>>> root = list_to_tree(path_list)
>>> root.plot("-ok")
<Figure size 1280x960 with 1 Axes>

query

query(query, debug=False)

Query tree using Tree Definition Language.

Examples:

>>> from bigtree import list_to_tree
>>> path_list = ["a/b/d", "a/b/e/g", "a/b/e/h", "a/c/f"]
>>> root = list_to_tree(path_list)
>>> root.query("depth == 2")
[Node(/a/b, ), Node(/a/c, )]

Parameters:

Name	Type	Description	Default
query	str	query	required
debug	bool	if True, will print out the parsed query	False

Returns:

Type	Description
list[T]	List of nodes that fulfil the condition of query