d3-hierarchy hierarchy node methods
Hierarchy node methods: node.ancestors (generate array of ancestors), node.descendants (generate array of descendants), node.leaves (generate array of leaves), node.find (find node in hierarchy), node.path (generate shortest path to another node), node.links (generate array of links), node.sum (evaluate and aggregate quantitative values), node.count (count leaves), node.sort (sort descendant siblings), node.each (breadth-first traversal), node.eachAfter (post-order traversal), node.eachBefore (pre-order traversal), node.copy (copy hierarchy).
node.descendants() method
node.descendants() returns an array of descendant nodes starting with the node itself, then followed by each child in topological order.
node.leaves() method
node.leaves() returns an array of leaf nodes in traversal order. A leaf is a node with no children.
node.find(filter) method
node.find(filter) returns the first node in the hierarchy from this node for which the specified filter function returns a truthy value. Returns undefined if no such node is found.
d3.hierarchy() function signature
d3.hierarchy(data, children) constructs a root node from hierarchical data. The data parameter must be an object representing the root node. The optional children parameter is an accessor function that returns an iterable of child data for each datum. If not specified, it defaults to function children(d) { return d.children; }. If data is a Map, it is implicitly converted to [undefined, data], and the children accessor defaults to function children(d) { return Array.isArray(d) ? d[1] : null; }.
Hierarchy node properties
A node returned by d3.hierarchy() and each of its descendants has these properties: node.data (the associated data passed to hierarchy), node.depth (zero for root, increasing by one per generation), node.height (greatest distance from any descendant leaf, zero for leaves), node.parent (parent node, null for root), node.children (array of child nodes if any, undefined for leaves), node.value (optional summed value of node and descendants).
node.ancestors() method
node.ancestors() returns an array of ancestor nodes starting with the node itself, then followed by each parent up to the root.
node.path(target) method
node.path(target) 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 both nodes, and then descends to the target node. This is useful for hierarchical edge bundling.
node.links() method
node.links() returns an array of links for this node and its descendants, where each link is an object with source and target properties. The source of each link is the parent node, and the target is a child node.
node.sum(value) method
node.sum(value) 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 function plus the combined value of all children. The function is passed the node's data and must return a non-negative number. Must be called before invoking hierarchical layouts that require node.value, such as treemap.
node.count() method
node.count() computes the number of leaves under this node and assigns it to node.value, similarly for every descendant. If the node is a leaf, its count is one. Returns this node.
node.sort(compare) method
node.sort(compare) sorts the children of this node and each of this node's descendants' children in pre-order traversal using the specified compare function, and returns this node. The compare function receives two nodes a and b. It must return a value less than zero if a should be before b, greater than zero if b should be before a, or any value for unspecified relative order. Must be called before invoking a hierarchical layout if you want the sort order to affect the layout.
node[Symbol.iterator]() iterator
node[Symbol.iterator]() returns an iterator over the node's descendants in breadth-first order, allowing iteration with for...of loops.
node.each(function, that) method
node.each(function, that) invokes the specified function for this 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 function receives the current descendant, the zero-based traversal index, and this node. If that is specified, it is the this context of the callback.
node.eachAfter(function, that) method
node.eachAfter(function, that) invokes the specified function for this 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 function receives the current descendant, the zero-based traversal index, and this node. If that is specified, it is the this context of the callback.
node.eachBefore(function, that) method
node.eachBefore(function, that) invokes the specified function for this 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 function receives the current descendant, the zero-based traversal index, and this node. If that is specified, it is the this context of the callback.
node.copy() method
node.copy() returns a deep copy of the subtree starting at this node. The returned deep copy shares the same data. The returned node is the root of a new tree; the returned node's parent is always null and its depth is always zero.
Example treemap layout with hierarchy
This example shows how to construct and compute a treemap layout with hierarchy: const treemap = d3.treemap(); treemap.size([width, height]); treemap.padding(2); root.sum((d) => d.value); root.sort((a, b) => b.height - a.height || b.value - a.value); treemap(root); const nodes = root.descendants();
Example hierarchy data structure
Example hierarchical data structure: const data = { name: "Eve", children: [ {name: "Cain"}, {name: "Seth", children: [{name: "Enos"}, {name: "Noam"}]}, {name: "Abel"}, {name: "Awan", children: [{name: "Enoch"}]}, {name: "Azura"} ] };
Example node.sum for counting leaves
Example using node.sum as an alternative to node.count for only counting leaf nodes: root.sum((d) => d.value ? 1 : 0);
Example sorting nodes by value
Example sorting nodes by descending aggregate value of the node and all its descendants, as recommended for circle-packing: root.sum((d) => d.value).sort((a, b) => b.value - a.value);
Example sorting nodes by height and value
Example sorting nodes by descending height (greatest distance from any descendant leaf) and then descending value, as recommended for treemaps and icicles: root.sum((d) => d.value).sort((a, b) => b.height - a.height || b.value - a.value);
Example sorting nodes by height and id
Example sorting nodes by descending height and then ascending id, as recommended for trees and dendrograms: root.sum((d) => d.value).sort((a, b) => b.height - a.height || d3.ascending(a.id, b.id));
Example iterating over descendants with for...of
Example iterating over node's descendants in breadth-first order: for (const descendant of node) { console.log(descendant); }