Hierarchies

detroit.hierarchy(data: dict[str, Any] | Node, children: Callable[[dict[str, Any]], Any | None] = None) → Node

Builds a root node from the specified hierarchical data. The specified data must be an object representing the root node.

Parameters:

  • data (dict[str, Any] | Node) – Data

  • children (Callable[[dict[str, Any]], Any | None]) – Accessor function to get data children

Returns:

Hierarchy node object

Return type:

Node

class detroit.hierarchy.hierarchy.Node(data: Any)

Node object

Parameters:

data (Any) – Data

data

The associated data

Type:

Any

depth

Zero for the root, increasing by one for each descendant generation

Type:

int

height

Greatest distance from any descendant leaf, or zero for leaves

Type:

int

parent

The parent node or None for the root node

Type:

Node | None

value

Optional summed value of the node and its descendants

Type:

float | None

children

An array of child nodes, if any, or undefined for leaves

Type:

list[Node] | None

__iter__() → Iterator[Node]

Returns an iterator over the node’s descendants in breadth-first order.

Returns:

Iterator over the node’s descendants

Return type:

Iterator[Node]

ancestors() → list[Node]

Returns the array of ancestors nodes, starting with this node, then followed by each parent up to the root.

Returns:

List of ancestors

Return type:

list[Node]

copy() → Node

Return a deep copy of the subtree starting at this node. (The returned deep copy shares the same data, however.). The returned node is the root of a new tree; the returned node’s parent is always null and its depth is always zero.

Returns:

Copied node

Return type:

Node

count() → int

Computes the number of leaves under this node and assigns it to node.value, and similarly for every descendant of node. If this node is a leaf, its count is one. Returns this node. See also node.sum.

Returns:

Number of leaves

Return type:

int

descendants() → list[Node]

Returns the array of descendant nodes, starting with this node, then followed by each child in topological order.

Returns:

Descendant nodes

Return type:

list[Node]

each(callback: Callable[[Node, int, Node], None]) → Node

Invokes the specified function for node and each descendant in breadth-first order, such that a given node is only visited if all nodes of lesser depth have already been visited, as well as all preceding nodes of the same depth. The specified function is passed the current descendant, the zero-based traversal index, and this node. If that is specified, it is the this context of the callback.

Parameters:

callback (Callable[[Node, int, Node], None]) –

Function to call which takes as argument:

  • node (Node) - the descendant node

  • i (int) - the index of the descendant node

  • self (Node) - the current node itself

Returns:

Itself

Return type:

Node

each_after(callback: Callable[[Node, int, Node], None]) → Node

Invokes the specified function for node and each descendant in post-order traversal, such that a given node is only visited after all of its descendants have already been visited. The specified function is passed the current descendant, the zero-based traversal index, and this node. If that is specified, it is the this context of the callback.

Parameters:

callback (Callable[[Node, int, Node], None]) –

Function to call which takes as argument:

  • node (Node) - the descendant node

  • i (int) - the index of the descendant node

  • self (Node) - the current node itself

Returns:

Itself

Return type:

Node

each_before(callback: Callable[[Node, int, Node], None]) → Node

Invokes the specified function for node and each descendant in pre-order traversal, such that a given node is only visited after all of its ancestors have already been visited. The specified function is passed the current descendant, the zero-based traversal index, and this node. If that is specified, it is the this context of the callback.

Parameters:

callback (Callable[[Node, int, Node], None]) –

Function to call which takes as argument:

  • node (Node) - the descendant node

  • i (int) - the index of the descendant node

  • self (Node) - the current node itself

Returns:

Itself

Return type:

Node

find(callback: Callable[[Node, int, Node], None]) → Node

Returns the first node in the hierarchy from this node for which the specified filter returns a truthy value. Returns undefined if no such node is found.

Parameters:

callback (Callable[[Node, int, Node], None]) –

Function to call which takes as argument:

  • node (Node) - the descendant node

  • i (int) - the index of the descendant node

  • self (Node) - the current node itself

Returns:

Itself

Return type:

Node

leaves() → list[Node]

Returns the array of leaf nodes in traversal order. A leaf is a node with no children.

Returns:

Leaf nodes

Return type:

list[Node]

Returns an array of links for this node and its descendants, where each link is an object that defines source and target properties. The source of each link is the parent node, and the target is a child node.

Returns:

List of links where link = {"source": node.parent, "target": node}

Return type:

list[dict[str, Node]]

path(end: Node) → list[Node]

Returns the shortest path through the hierarchy from this node to the specified target node. The path starts at this node, ascends to the least common ancestor of this node and the target node, and then descends to the target node. This is useful for hierarchical edge bundling.

Parameters:

end (Node) – Target

Returns:

List of nodes

Return type:

list[Node]

sort(compare: Callable[[Node], float]) → Node

Sorts the children of this node, if any, and each of this node’s descendants’ children, in pre-order traversal using the specified compare function, and returns this node.

Parameters:

compare (Callable[[Node], float]) – Compare key function

Returns:

Itself

Return type:

Node

Notes

functools.cmp_to_key should be used to compare two nodes.

from functools import cmp_to_key

def compare(a: Node, b: Node) -> float:
    a_value = 0. if a.value is None else a.value
    b_value = 0. if b.value is None else b.value
    return a_value - b_value

root = root.sort(compare=cmp_to_key(compare))
sum(value: Callable[[dict[str, Any]], float]) → Node

Evaluates the specified value function for this node and each descendant in post-order traversal, and returns this node. The node.value property of each node is set to the numeric value returned by the specified function plus the combined value of all children. The function is passed the node’s data, and must return a non-negative number. The value accessor is evaluated for node and every descendant, including internal nodes; if you only want leaf nodes to have internal value, then return zero for any node with children.

Parameters:

value (Callable[[dict[str, Any]], float]) – Function which takes the node’s data as input and return a float value as output

Returns:

Itself

Return type:

Node