GithubHelp home page GithubHelp logo

d3-hierarchy's Introduction

d3-hierarchy

Many datasets are intrinsically hierarchical. Consider geographic entities, such as census blocks, census tracts, counties and states; the command structure of businesses and governments; file systems and software packages. And even non-hierarchical data may be arranged empirically into a hierarchy, as with k-means clustering or phylogenetic trees.

This module implements several popular techniques for visualizing hierarchical data:

Node-link diagrams show topology using discrete marks for nodes and links, such as a circle for each node and a line connecting each parent and child. The “tidy” tree is delightfully compact, while the dendrogram places leaves at the same level. (These have both polar and Cartesian forms.) Indented trees are useful for interactive browsing.

Adjacency diagrams show topology through the relative placement of nodes. They may also encode a quantitative dimension in the area of each node, for example to show revenue or file size. The “icicle” diagram uses rectangles, while the “sunburst” uses annular segments.

Enclosure diagrams also use an area encoding, but show topology through containment. A treemap recursively subdivides area into rectangles. Circle-packing tightly nests circles; this is not as space-efficient as a treemap, but perhaps more readily shows topology.

A good hierarchical visualization facilitates rapid multiscale inference: micro-observations of individual elements and macro-observations of large groups.

Installing

If you use npm, npm install d3-hierarchy. You can also download the latest release on GitHub. For vanilla HTML in modern browsers, import d3-hierarchy from Skypack:

<script type="module">

import {treemap} from "https://cdn.skypack.dev/[email protected]";

const tree = treemap();

</script>

For legacy environments, you can load d3-hierarchy’s UMD bundle from an npm-based CDN such as jsDelivr; a d3 global is exported:

<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script>

const tree = d3.treemap();

</script>

API Reference

Hierarchy

Before you can compute a hierarchical layout, you need a root node. If your data is already in a hierarchical format, such as JSON, you can pass it directly to d3.hierarchy; otherwise, you can rearrange tabular data, such as comma-separated values (CSV), into a hierarchy using d3.stratify.

# d3.hierarchy(data[, children]) · Source, Examples

Constructs a root node from the specified hierarchical data. The specified data must be an object representing the root node. For example:

{
  "name": "Eve",
  "children": [
    {
      "name": "Cain"
    },
    {
      "name": "Seth",
      "children": [
        {
          "name": "Enos"
        },
        {
          "name": "Noam"
        }
      ]
    },
    {
      "name": "Abel"
    },
    {
      "name": "Awan",
      "children": [
        {
          "name": "Enoch"
        }
      ]
    },
    {
      "name": "Azura"
    }
  ]
}

The specified children accessor function is invoked for each datum, starting with the root data, and must return an iterable of data representing the children, if any. If the children accessor is not specified, it defaults to:

function children(d) {
  return d.children;
}

If data is a Map, it is implicitly converted to the entry [undefined, data], and the children accessor instead defaults to:

function children(d) {
  return Array.isArray(d) ? d[1] : null;
}

This allows you to pass the result of d3.group or d3.rollup to d3.hierarchy.

The returned node and each descendant has the following properties:

  • node.data - the associated data, as specified to the constructor.
  • node.depth - zero for the root node, and increasing by one for each descendant generation.
  • node.height - zero for leaf nodes, and the greatest distance from any descendant leaf for internal nodes.
  • node.parent - the parent node, or null for the root node.
  • node.children - an array of child nodes, if any; undefined for leaf nodes.
  • node.value - the summed value of the node and its descendants; optional, see node.sum and node.count.

This method can also be used to test if a node is an instanceof d3.hierarchy and to extend the node prototype.

# node.ancestors() · Source, Examples

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

# node.descendants() · Source, Examples

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

# node.leaves() · Source, Examples

Returns the array of leaf nodes in traversal order; leaves are nodes with no children.

# node.find(filter) · Source

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

# node.path(target) · Source, Examples

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 particularly useful for hierarchical edge bundling.

# node.links() · Source, Examples

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.

# node.sum(value) · Source, Examples

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. For example, as an alternative to node.count:

root.sum(function(d) { return d.value ? 1 : 0; });

You must call node.sum or node.count before invoking a hierarchical layout that requires node.value, such as d3.treemap. Since the API supports method chaining, you can invoke node.sum and node.sort before computing the layout, and then subsequently generate an array of all descendant nodes like so:

var treemap = d3.treemap()
    .size([width, height])
    .padding(2);

var nodes = treemap(root
    .sum(function(d) { return d.value; })
    .sort(function(a, b) { return b.height - a.height || b.value - a.value; }))
  .descendants();

This example assumes that the node data has a value field.

# node.count() · Source, Examples

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.

# node.sort(compare) · Source, Examples

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. The specified function is passed two nodes a and b to compare. If a should be before b, the function must return a value less than zero; if b should be before a, the function must return a value greater than zero; otherwise, the relative order of a and b are not specified. See array.sort for more.

Unlike node.sum, the compare function is passed two nodes rather than two nodes’ data. For example, if the data has a value property, this sorts nodes by the descending aggregate value of the node and all its descendants, as is recommended for circle-packing:

root
    .sum(function(d) { return d.value; })
    .sort(function(a, b) { return b.value - a.value; });

Similarly, to sort nodes by descending height (greatest distance from any descendant leaf) and then descending value, as is recommended for treemaps and icicles:

root
    .sum(function(d) { return d.value; })
    .sort(function(a, b) { return b.height - a.height || b.value - a.value; });

To sort nodes by descending height and then ascending id, as is recommended for trees and dendrograms:

root
    .sum(function(d) { return d.value; })
    .sort(function(a, b) { return b.height - a.height || a.id.localeCompare(b.id); });

You must call node.sort before invoking a hierarchical layout if you want the new sort order to affect the layout; see node.sum for an example.

# node[Symbol.iterator]() <>

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

for (const descendant of node) {
  console.log(descendant);
}

# node.each(function[, that]) · Source, Examples

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.

# node.eachAfter(function[, that]) · Source, Examples

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.

# node.eachBefore(function[, that]) · Source, Examples

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.

# node.copy() · Source, Examples

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.

Stratify

Consider the following table of relationships:

Name Parent
Eve
Cain Eve
Seth Eve
Enos Seth
Noam Seth
Abel Eve
Awan Eve
Enoch Awan
Azura Eve

These names are conveniently unique, so we can unambiguously represent the hierarchy as a CSV file:

name,parent
Eve,
Cain,Eve
Seth,Eve
Enos,Seth
Noam,Seth
Abel,Eve
Awan,Eve
Enoch,Awan
Azura,Eve

To parse the CSV using d3.csvParse:

var table = d3.csvParse(text);

This returns:

[
  {"name": "Eve",   "parent": ""},
  {"name": "Cain",  "parent": "Eve"},
  {"name": "Seth",  "parent": "Eve"},
  {"name": "Enos",  "parent": "Seth"},
  {"name": "Noam",  "parent": "Seth"},
  {"name": "Abel",  "parent": "Eve"},
  {"name": "Awan",  "parent": "Eve"},
  {"name": "Enoch", "parent": "Awan"},
  {"name": "Azura", "parent": "Eve"}
]

To convert to a hierarchy:

var root = d3.stratify()
    .id(function(d) { return d.name; })
    .parentId(function(d) { return d.parent; })
    (table);

This returns:

Stratify

This hierarchy can now be passed to a hierarchical layout, such as d3.tree, for visualization.

# d3.stratify() · Source, Examples

Constructs a new stratify operator with the default settings.

# stratify(data) · Source, Examples

Generates a new hierarchy from the specified tabular data.

# stratify.id([id]) · Source, Examples

If id is specified, sets the id accessor to the given function and returns this stratify operator. Otherwise, returns the current id accessor, which defaults to:

function id(d) {
  return d.id;
}

The id accessor is invoked for each element in the input data passed to the stratify operator, being passed the current datum (d) and the current index (i). The returned string is then used to identify the node’s relationships in conjunction with the parent id. For leaf nodes, the id may be undefined; otherwise, the id must be unique. (Null and the empty string are equivalent to undefined.)

# stratify.parentId([parentId]) · Source, Examples

If parentId is specified, sets the parent id accessor to the given function and returns this stratify operator. Otherwise, returns the current parent id accessor, which defaults to:

function parentId(d) {
  return d.parentId;
}

The parent id accessor is invoked for each element in the input data passed to the stratify operator, being passed the current datum (d) and the current index (i). The returned string is then used to identify the node’s relationships in conjunction with the id. For the root node, the parent id should be undefined. (Null and the empty string are equivalent to undefined.) There must be exactly one root node in the input data, and no circular relationships.

# stratify.path([path]) · Source, Examples

If path is specified, sets the path accessor to the given function and returns this stratify operator. Otherwise, returns the current path accessor, which defaults to undefined. If a path accessor is set, the id and parentId arguments are ignored, and a unix-like hierarchy is computed on the slash-delimited strings returned by the path accessor, imputing parent nodes and ids as necessary.

d3.stratify().path(d => d)(["a/b", "a/c"]); // nodes with id "/a", "/a/b", "/a/c"

Cluster

Dendrogram

The cluster layout produces dendrograms: node-link diagrams that place leaf nodes of the tree at the same depth. Dendrograms are typically less compact than tidy trees, but are useful when all the leaves should be at the same level, such as for hierarchical clustering or phylogenetic tree diagrams.

# d3.cluster() · Source, Examples

Creates a new cluster layout with default settings.

# cluster(root)

Lays out the specified root hierarchy, assigning the following properties on root and its descendants:

  • node.x - the x-coordinate of the node
  • node.y - the y-coordinate of the node

The coordinates x and y represent an arbitrary coordinate system; for example, you can treat x as an angle and y as a radius to produce a radial layout. You may want to call root.sort before passing the hierarchy to the cluster layout.

# cluster.size([size])

If size is specified, sets this cluster layout’s size to the specified two-element array of numbers [width, height] and returns this cluster layout. If size is not specified, returns the current layout size, which defaults to [1, 1]. A layout size of null indicates that a node size will be used instead. The coordinates x and y represent an arbitrary coordinate system; for example, to produce a radial layout, a size of [360, radius] corresponds to a breadth of 360° and a depth of radius.

# cluster.nodeSize([size])

If size is specified, sets this cluster layout’s node size to the specified two-element array of numbers [width, height] and returns this cluster layout. If size is not specified, returns the current node size, which defaults to null. A node size of null indicates that a layout size will be used instead. When a node size is specified, the root node is always positioned at ⟨0, 0⟩.

# cluster.separation([separation])

If separation is specified, sets the separation accessor to the specified function and returns this cluster layout. If separation is not specified, returns the current separation accessor, which defaults to:

function separation(a, b) {
  return a.parent == b.parent ? 1 : 2;
}

The separation accessor is used to separate neighboring leaves. The separation function is passed two leaves a and b, and must return the desired separation. The nodes are typically siblings, though the nodes may be more distantly related if the layout decides to place such nodes adjacent.

Tree

Tidy Tree

The tree layout produces tidy node-link diagrams of trees using the Reingold–Tilford “tidy” algorithm, improved to run in linear time by Buchheim et al. Tidy trees are typically more compact than dendrograms.

# d3.tree() · Source, Examples

Creates a new tree layout with default settings.

# tree(root)

Lays out the specified root hierarchy, assigning the following properties on root and its descendants:

  • node.x - the x-coordinate of the node
  • node.y - the y-coordinate of the node

The coordinates x and y represent an arbitrary coordinate system; for example, you can treat x as an angle and y as a radius to produce a radial layout. You may want to call root.sort before passing the hierarchy to the tree layout.

# tree.size([size])

If size is specified, sets this tree layout’s size to the specified two-element array of numbers [width, height] and returns this tree layout. If size is not specified, returns the current layout size, which defaults to [1, 1]. A layout size of null indicates that a node size will be used instead. The coordinates x and y represent an arbitrary coordinate system; for example, to produce a radial layout, a size of [360, radius] corresponds to a breadth of 360° and a depth of radius.

# tree.nodeSize([size])

If size is specified, sets this tree layout’s node size to the specified two-element array of numbers [width, height] and returns this tree layout. If size is not specified, returns the current node size, which defaults to null. A node size of null indicates that a layout size will be used instead. When a node size is specified, the root node is always positioned at ⟨0, 0⟩.

# tree.separation([separation])

If separation is specified, sets the separation accessor to the specified function and returns this tree layout. If separation is not specified, returns the current separation accessor, which defaults to:

function separation(a, b) {
  return a.parent == b.parent ? 1 : 2;
}

A variation that is more appropriate for radial layouts reduces the separation gap proportionally to the radius:

function separation(a, b) {
  return (a.parent == b.parent ? 1 : 2) / a.depth;
}

The separation accessor is used to separate neighboring nodes. The separation function is passed two nodes a and b, and must return the desired separation. The nodes are typically siblings, though the nodes may be more distantly related if the layout decides to place such nodes adjacent.

Treemap

Treemap

Introduced by Ben Shneiderman in 1991, a treemap recursively subdivides area into rectangles according to each node’s associated value. D3’s treemap implementation supports an extensible tiling method: the default squarified method seeks to generate rectangles with a golden aspect ratio; this offers better readability and size estimation than slice-and-dice, which simply alternates between horizontal and vertical subdivision by depth.

# d3.treemap() · Source, Examples

Creates a new treemap layout with default settings.

# treemap(root)

Lays out the specified root hierarchy, assigning the following properties on root and its descendants:

  • node.x0 - the left edge of the rectangle
  • node.y0 - the top edge of the rectangle
  • node.x1 - the right edge of the rectangle
  • node.y1 - the bottom edge of the rectangle

You must call root.sum before passing the hierarchy to the treemap layout. You probably also want to call root.sort to order the hierarchy before computing the layout.

# treemap.tile([tile])

If tile is specified, sets the tiling method to the specified function and returns this treemap layout. If tile is not specified, returns the current tiling method, which defaults to d3.treemapSquarify with the golden ratio.

# treemap.size([size])

If size is specified, sets this treemap layout’s size to the specified two-element array of numbers [width, height] and returns this treemap layout. If size is not specified, returns the current size, which defaults to [1, 1].

# treemap.round([round])

If round is specified, enables or disables rounding according to the given boolean and returns this treemap layout. If round is not specified, returns the current rounding state, which defaults to false.

# treemap.padding([padding])

If padding is specified, sets the inner and outer padding to the specified number or function and returns this treemap layout. If padding is not specified, returns the current inner padding function.

# treemap.paddingInner([padding])

If padding is specified, sets the inner padding to the specified number or function and returns this treemap layout. If padding is not specified, returns the current inner padding function, which defaults to the constant zero. If padding is a function, it is invoked for each node with children, being passed the current node. The inner padding is used to separate a node’s adjacent children.

# treemap.paddingOuter([padding])

If padding is specified, sets the top, right, bottom and left padding to the specified number or function and returns this treemap layout. If padding is not specified, returns the current top padding function.

# treemap.paddingTop([padding])

If padding is specified, sets the top padding to the specified number or function and returns this treemap layout. If padding is not specified, returns the current top padding function, which defaults to the constant zero. If padding is a function, it is invoked for each node with children, being passed the current node. The top padding is used to separate the top edge of a node from its children.

# treemap.paddingRight([padding])

If padding is specified, sets the right padding to the specified number or function and returns this treemap layout. If padding is not specified, returns the current right padding function, which defaults to the constant zero. If padding is a function, it is invoked for each node with children, being passed the current node. The right padding is used to separate the right edge of a node from its children.

# treemap.paddingBottom([padding])

If padding is specified, sets the bottom padding to the specified number or function and returns this treemap layout. If padding is not specified, returns the current bottom padding function, which defaults to the constant zero. If padding is a function, it is invoked for each node with children, being passed the current node. The bottom padding is used to separate the bottom edge of a node from its children.

# treemap.paddingLeft([padding])

If padding is specified, sets the left padding to the specified number or function and returns this treemap layout. If padding is not specified, returns the current left padding function, which defaults to the constant zero. If padding is a function, it is invoked for each node with children, being passed the current node. The left padding is used to separate the left edge of a node from its children.

Treemap Tiling

Several built-in tiling methods are provided for use with treemap.tile.

# d3.treemapBinary(node, x0, y0, x1, y1) · Source, Examples

Recursively partitions the specified nodes into an approximately-balanced binary tree, choosing horizontal partitioning for wide rectangles and vertical partitioning for tall rectangles.

# d3.treemapDice(node, x0, y0, x1, y1) · Source, Examples

Divides the rectangular area specified by x0, y0, x1, y1 horizontally according the value of each of the specified node’s children. The children are positioned in order, starting with the left edge (x0) of the given rectangle. If the sum of the children’s values is less than the specified node’s value (i.e., if the specified node has a non-zero internal value), the remaining empty space will be positioned on the right edge (x1) of the given rectangle.

# d3.treemapSlice(node, x0, y0, x1, y1) · Source, Examples

Divides the rectangular area specified by x0, y0, x1, y1 vertically according the value of each of the specified node’s children. The children are positioned in order, starting with the top edge (y0) of the given rectangle. If the sum of the children’s values is less than the specified node’s value (i.e., if the specified node has a non-zero internal value), the remaining empty space will be positioned on the bottom edge (y1) of the given rectangle.

# d3.treemapSliceDice(node, x0, y0, x1, y1) · Source, Examples

If the specified node has odd depth, delegates to treemapSlice; otherwise delegates to treemapDice.

# d3.treemapSquarify(node, x0, y0, x1, y1) · Source, Examples

Implements the squarified treemap algorithm by Bruls et al., which seeks to produce rectangles of a given aspect ratio.

# d3.treemapResquarify(node, x0, y0, x1, y1) · Source, Examples

Like d3.treemapSquarify, except preserves the topology (node adjacencies) of the previous layout computed by d3.treemapResquarify, if there is one and it used the same target aspect ratio. This tiling method is good for animating changes to treemaps because it only changes node sizes and not their relative positions, thus avoiding distracting shuffling and occlusion. The downside of a stable update, however, is a suboptimal layout for subsequent updates: only the first layout uses the Bruls et al. squarified algorithm.

# squarify.ratio(ratio) · Source, Examples

Specifies the desired aspect ratio of the generated rectangles. The ratio must be specified as a number greater than or equal to one. Note that the orientation of the generated rectangles (tall or wide) is not implied by the ratio; for example, a ratio of two will attempt to produce a mixture of rectangles whose width:height ratio is either 2:1 or 1:2. (However, you can approximately achieve this result by generating a square treemap at different dimensions, and then stretching the treemap to the desired aspect ratio.) Furthermore, the specified ratio is merely a hint to the tiling algorithm; the rectangles are not guaranteed to have the specified aspect ratio. If not specified, the aspect ratio defaults to the golden ratio, φ = (1 + sqrt(5)) / 2, per Kong et al.

Partition

Partition

The partition layout produces adjacency diagrams: a space-filling variant of a node-link tree diagram. Rather than drawing a link between parent and child in the hierarchy, nodes are drawn as solid areas (either arcs or rectangles), and their placement relative to other nodes reveals their position in the hierarchy. The size of the nodes encodes a quantitative dimension that would be difficult to show in a node-link diagram.

# d3.partition() · Source, Examples

Creates a new partition layout with the default settings.

# partition(root)

Lays out the specified root hierarchy, assigning the following properties on root and its descendants:

  • node.x0 - the left edge of the rectangle
  • node.y0 - the top edge of the rectangle
  • node.x1 - the right edge of the rectangle
  • node.y1 - the bottom edge of the rectangle

You must call root.sum before passing the hierarchy to the partition layout. You probably also want to call root.sort to order the hierarchy before computing the layout.

# partition.size([size])

If size is specified, sets this partition layout’s size to the specified two-element array of numbers [width, height] and returns this partition layout. If size is not specified, returns the current size, which defaults to [1, 1].

# partition.round([round])

If round is specified, enables or disables rounding according to the given boolean and returns this partition layout. If round is not specified, returns the current rounding state, which defaults to false.

# partition.padding([padding])

If padding is specified, sets the padding to the specified number and returns this partition layout. If padding is not specified, returns the current padding, which defaults to zero. The padding is used to separate a node’s adjacent children.

Pack

Circle-Packing

Enclosure diagrams use containment (nesting) to represent a hierarchy. The size of the leaf circles encodes a quantitative dimension of the data. The enclosing circles show the approximate cumulative size of each subtree, but due to wasted space there is some distortion; only the leaf nodes can be compared accurately. Although circle packing does not use space as efficiently as a treemap, the “wasted” space more prominently reveals the hierarchical structure.

# d3.pack() · Source, Examples

Creates a new pack layout with the default settings.

# pack(root)

Lays out the specified root hierarchy, assigning the following properties on root and its descendants:

  • node.x - the x-coordinate of the circle’s center
  • node.y - the y-coordinate of the circle’s center
  • node.r - the radius of the circle

You must call root.sum before passing the hierarchy to the pack layout. You probably also want to call root.sort to order the hierarchy before computing the layout.

# pack.radius([radius])

If radius is specified, sets the pack layout’s radius accessor to the specified function and returns this pack layout. If radius is not specified, returns the current radius accessor, which defaults to null. If the radius accessor is null, the radius of each leaf circle is derived from the leaf node.value (computed by node.sum); the radii are then scaled proportionally to fit the layout size. If the radius accessor is not null, the radius of each leaf circle is specified exactly by the function.

# pack.size([size])

If size is specified, sets this pack layout’s size to the specified two-element array of numbers [width, height] and returns this pack layout. If size is not specified, returns the current size, which defaults to [1, 1].

# pack.padding([padding])

If padding is specified, sets this pack layout’s padding accessor to the specified number or function and returns this pack layout. If padding is not specified, returns the current padding accessor, which defaults to the constant zero. When siblings are packed, tangent siblings will be separated by approximately the specified padding; the enclosing parent circle will also be separated from its children by approximately the specified padding. If an explicit radius is not specified, the padding is approximate because a two-pass algorithm is needed to fit within the layout size: the circles are first packed without padding; a scaling factor is computed and applied to the specified padding; and lastly the circles are re-packed with padding.

# d3.packSiblings(circles) · Source

Packs the specified array of circles, each of which must have a circle.r property specifying the circle’s radius. Assigns the following properties to each circle:

  • circle.x - the x-coordinate of the circle’s center
  • circle.y - the y-coordinate of the circle’s center

The circles are positioned according to the front-chain packing algorithm by Wang et al.

# d3.packEnclose(circles) · Source, Examples

Computes the smallest circle that encloses the specified array of circles, each of which must have a circle.r property specifying the circle’s radius, and circle.x and circle.y properties specifying the circle’s center. The enclosing circle is computed using the Matoušek-Sharir-Welzl algorithm. (See also Apollonius’ Problem.)

d3-hierarchy's People

Contributors

dechov avatar denisname avatar dependabot[bot] avatar erimcg avatar fil avatar mbostock avatar robinhouston avatar rohanpadhye avatar stof avatar vasturiano avatar vorontsovie avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

d3-hierarchy's Issues

Add DOM-style hierarchy traversal methods?

I am working with some large-ish hierarchies, with over 10,000 nodes, and a bit of custom data. Too large to be in the DOM all at once, so they need to be queried. I am finding that I often need to be able to traverse a hierarchy, starting from a given node, looking for a node that satisfies some condition. This is straightforward to do manually, but in results in a lot of for loops, which aren't really in the D3 idiom. The existing each-* methods have the slight performance disadvantage that there is no way early-exit the loop once the target node has been found. It might be nice to have that option as an API refinement.

Another option could be jQuery-esque .closest and .find methods that looked up and down the hierarchy, respectively, and returned the first "matching" node.

Thanks.

Level-specific treemap padding.

It’d be nice to:

  • Avoid rendering (or at least padding) the root node.
  • Terminating outer padding after some levels of depth.

Perhaps treemap.padding should take a function, as in 3.x.

More descriptive stratify errors.

This would be especially helpful to people using d3-stratify for the first time, such as forking an example like Tidy Tree and trying to input their own data.

Some ideas about what the text might be.

  • d3-stratify: cannot accept multiple root nodes
  • d3-stratify: requires a root node to create a valid hierarchy
  • d3-stratify: this parent id is missing from the hierarchy: nodeId
  • d3-stratify: ambiguous reference: nodeId matches two parents

image

Sorting nodes by “height” before computing a layout.

The problem is that the root isn’t constructed until you call treemap(data), which makes it hard to use the node API to compute things like node height. So… maybe we should change the hierarchical layouts to once again take a node as input rather than data, and use node.clone if you don’t want to mutate the data.

[feat] parse method on stratify constructor

Aside from making it more extensible, it would be handy to have the ability to keep the parentId & id out of the node's data property.

I'm working on it at the moment, just raising the issue.

d3v4 hierarchy().sum() vs d3v3 partition.value() differences?

Using the partition layout I have created a Icicle tree using both d3v3 and d3v4 where the height of a node should be the number of children it contains. However, the d3v4 hierarchy.sum() produces different dimensions than d3v3 partition.value().

v3

    var partition = d3Old.layout.partition()
        .size([height,width])
        .value(function(d) { return 1; })
        .children(getChildren)
        .sort(null)

    var nodes = partition.nodes(data);

    g2.selectAll("rect")
        .data(nodes)
      .enter()
        .append("rect")
            .attr("x", function(d) { return d.y; })
            .attr("y", function(d) { return d.x; })
            .attr("width", function(d) { return d.dy; })
            .attr("height", function(d) { return d.dx; })
            .attr('fill', function(d) {
                var type = htmlElementType[d.name];
                //debugging 
                if(type === undefined) {
                    console.log(d.data);
                    return colorScale(16);
                } else { 
                    return colorScale(COLOR[type]);
                }
            })
            .attr('stroke', 'black')

v4

    var root = d3.hierarchy(data, getChildren)
        .sum( function(d) { 
            return 1;
        })
        .sort(null);

    var partition = d3.partition()
                 .size([height, width])
                 .padding(0)
                 //.round(f);

    partition(root);

  var nodes = g1.selectAll('rect')
        .data(root.descendants())
      .enter()
        .append('rect')
            .attr('fill', function(d) {
                var type = htmlElementType[d.data.name];
                //debugging 
                if(type === undefined) {
                    console.log(d.data);
                    return colorScale(16);
                } else { 
                    return colorScale(COLOR[type]);
                }
            })
            .attr('stroke', 'black')
            .attr("x", function(d) { return d.y0; })
            .attr("y", function(d) { return d.x0; })
            .attr("width", function(d) { return d.y1 - d.y0; })
            .attr("height", function(d) { return d.x1 - d.x0; })

screen_shot_2016-07-28_at_12_30_01

screen_shot_2016-07-28_at_12_37_05

stratify: how to stratify duplicated data?

d3.stratify() cannot parse csv file with duplicated data.
However, I want to represent a structure like this:
image
my csv file looks like this:

id
a,
a.b,
a.b

When I use stratify(), it returns "duplicate: a.b". How can I achieve it?

Bug in treemapDice in K value calculation

Found a bug in treemapDice that calculates an incorrect k value. Since parent.value includes the count of itself, k should be calculated as follows:

k = parent.value && (x1 - x0) / (parent.value-1)

rather than

k = parent.value && (x1 - x0) / parent.value

Found this bug since there were tiny gaps at the bottom of my partition map that was equal to size of the leaf node.

Stratify could infer implied parent nodes?

In the existing d3.stratify examples, it seems parent nodes must be included in the original CSV.

Example: http://bl.ocks.org/mbostock/9d0899acb5d3b8d839d9d613a9e1fe04

id,value
flare,
flare.analytics,
flare.analytics.cluster,
flare.analytics.cluster.AgglomerativeCluster,3938

It would be convenient if the first 3 rows in the above weren't required. In other words, this would be sufficient:

id,value
flare.analytics.cluster.AgglomerativeCluster,3938
flare.analytics.cluster.CommunityStructure,3812
flare.analytics.cluster.HierarchicalCluster,6714
flare.analytics.cluster.MergeEdge,743

The nodes flare, flare.analytics, and flare.analytics.cluster would be created automatically in the resulting hierarchy. Currently running the stratify function against the above CSV would throw an error like this:

Error: missing: flare.analytics.cluster

From this line of d3.stratify:

if (!parent) throw new Error("missing: " + nodeId);

if (!parent) throw new Error("missing: " + nodeId);

Translate circles after packing siblings.

The change in 0.2.1 makes d3.packSiblings somewhat unpredictable, since the weighted centroid can drift an arbitrary distance away from the origin. It’d be better to translate everything back to the origin when we’re done. Although note that this step is not necessary for d3.pack, since that will compute the enclosing circle and translate to its center. We should probably have a private method for packing siblings that is separate from the public one.

Example Code under node.sort(compare)

The first example under the node.sort(compare) contains the code snippet:

.sort(function(a, b) { return b.value - a.value; });

This should probably read:

.sort(function(a, b) { return b.data.value - a.data.value; });

as the sort function passes in nodes.

Squarify shouldn’t be stable by default? How to reset?

The squarified treemap layout stores the squarified layout in node._squarify. This means you can clear the metadata to recompute a non-stable layout like so:

treemap(root.eachBefore(function(d) { delete d._squarify; }));

Yet this is non-obvious and not documented.

  • Should the squarified layout store the metadata by default?
  • Should the squarified layout compute a stable layout by default if metadata is present?
  • How does one clear the stored metadata to compute a fresh layout?

Treemap Layout

I'm using the new v4 treemap layout with a squarified tile.
The ending at the bottom righ corner seems strange, whats the issue here?
screenshot 2016-06-22 11 08 09

<script>

var width = 800,
    height = 680;

var format = d3.format(",d");

var color = d3.scaleOrdinal()
    .range(d3.scaleOrdinal(d3.schemeCategory10).range()
        .map(function(c) { c = d3.rgb(c); c.opacity = 0.6; return c; }));

var stratify = d3.stratify()
    .parentId(function(d) { return d.id.substring(0, d.id.lastIndexOf(".")); });

var treemap = d3.treemap()
    .size([width, height])
    .padding(1)
    .round(true)
    .tile(d3["treemapSquarify"] ); // Squarify, Slice, SliceDice, Binary


d3.csv("product_view.csv", type, function(error, data) {
  if (error) throw error;

  var root = stratify(data)
      .sum(function(d) { return d.value; })

  treemap(root);


  d3.select("body")
    .selectAll(".node")
    .data(root.leaves())
    .enter().append("div")
      .attr("class", "node")
      .attr("title", function(d) { return d.id + "\n" + format(d.value); })
      .style("left", function(d) { return d.x0 + "px"; })
      .style("top", function(d) { return d.y0 + "px"; })
      .style("width", function(d) { return d.x1 - d.x0 + "px"; })
      .style("height", function(d) { return d.y1 - d.y0 + "px"; })
      .style("background", function(d) { while (d.depth > 1) d = d.parent; return color(d.id); })
      .text(function(d) { return d.id.substring(d.id.lastIndexOf(".") + 1).split(/(?=[A-Z][^A-Z])/g).join("\n"); })
    .append("div")
      .attr("class", "node-value")
      .text(function(d) { return format(d.value); });
});

function type(d) {
  d.value = +d.value;
  return d;
}

</script>

circle packing layout

Hi,

I was re-implementing the circle packing algorithm by Wang et al. in C, based on the old implementation in Protovis and noticed that you changed their algorithm so that each circle is put next to the previously placed circle instead of the location closest to the center of the plot. I assume it was intentional to keep nodes with the same color next to each other even so the final layout is less round, but more snail-shaped.
It's just a little modification to the code to change the placement according to the original algorithm, and I could provide it if desired (modified the big D3.js and it worked). Let me know..

Also: great work on D3 btw :)

cheers

Compute enclosing circle using only the front chain.

Currently we compute the enclosing circle using none of the information previously gained from packing siblings, but surely it would be more efficient to only consider circles in the front chain when computing the enclosing circle.

Treemap padding introduces bias, penalizing small nodes.

The treemap implementation subtracts a fixed amount of padding from the computed node sizes. This is simple to implement but disproportionately affects the size of small nodes, since the relative area of the subtracted padding is much higher with a small node than a big node.

In d3-shape’s pie generator, we go to some effort to ensure that the relative areas of padded arcs are preserved. We don’t do that with the treemap layout, in part because I presume it is more challenging to implement, but it would be lovely if we could. A two-pass approach might be an acceptable if imperfect solution: compute the layout without padding, compute the area lost to padding for each cell, add this to the value for the cell, and then recompute the layout.

Perhaps I should start by visualizing the distortion using the Flare hierarchy as an example dataset.

Related d3/d3-shape#41.

Accept tabular input data?

Rather than taking a tree as input (and a children accessor), it might be simpler if we took a table of nodes as input with id and parent accessors. For example:

id parent value
add methods 593
AgglomerativeCluster cluster 3938
AggregateExpression query 1616
analytics flare
AnchorControl controls 2138
and methods 330
And query 1027
animate flare
Arithmetic query 3891
ArrayInterpolator interpolate 1983
Arrays util 8258
ArrowType render 698
AspectRatioBanker optimization 7074

A more convenient way of computing height?

This is a little difficult to remember:

root.eachBefore(function(d) {
  var h = 0;
  do d.height = h;
  while ((d = d.parent) && (d.height < ++h));
});

We could compute it by default, as we do for depth. Or perhaps have a node.computeHeight() method.

Partition padding, so as to preserve relative areas?

If you do the simple thing and subtract a fixed amount of padding from the computed cells in a partition layout, you introduce distortion because small cells are disproportionately affected. It might be nice if the partition layout knew about padding, so that it could preserve the relative areas of padded cells.

See #19 for a description of a similar problem with the treemap layout.

error bundling with rollup 0.36.1

When creating a custom bundle using rollup 0.36.1 and the treemap function exported by d3-hierarchy, I get the following error in the browser console:

Uncaught TypeError: Cannot create property 'y0' on number '1.618033988749895'

Which points to the following line:
https://github.com/d3/d3-hierarchy/blob/master/src/treemap/index.js#L20

It only happens when I initialize the treemap function. If I comment out the line treemap() it bundles correctly.

import {treemap} from "d3-hierarchy";

export default function() {
  treemap();
}

Not sure if this is a d3-hierarchy bug or a rollup bug, so I apologize if this issue is misplaced.

node.links

I know it’s pretty trivial, but I think it’d be convenient.

Node.prototype.links = function() {
  var root = this, links = [];
  root.each(function(node) {
    if (node !== root) { // Don’t include the root’s parent, if any.
      links.push({source: node.parent, target: node});
    }
  });
  return links;
};

Why use undefined for leaf nodes rather than an empty list of children?

It seems to be one of those JavaScriptisms that really infuriate me, but I will leave this as a suggestion.

The hierarchy method fills the children field with a list of children if any, and undefined otherwise.

It seems to me that returning an empty list would be much more elegant and practical. For instance I could do:

// using ES5+ operators
node.children.map(...)
node.children.reduce(...)

Is there any good reason for not returning an empty list?
Good thing TypeScript with strictNullChecks warned me...

Sort nodes by depth then sibling order.

Currently nodes are returned in pre-order depth-first traversal. This means that siblings are adjacent and in their original order.

I believe it would be preferable to return nodes in breadth-first traversal order, by ascending depth. The root is first, as before, and then siblings are returned in the order defined by hierarchy.sort, defaulting to descending value. Thus, nodes at depth i + 1 are always drawn on top of nodes of depth i—not just their direct ancestors.

Squarify algorithm unresponsive to changed aspect ratio.

When a squarified layout is first calculated, partition decisions are cached on the tree nodes. If one then updates treemap.tile to use a squarified layout with a different target aspect ratio, this new ratio is effectively ignored in favor of the cached data. While stable layout is valuable in many situations, it is not always desired. In the case of assigning a new tiling method, my expectation was that this assignment would (by default) override any cached results. Perhaps the API could include a mechanism to make this determination user controllable.

This issue affects changes to the treemap.size parameter as well. Sometimes one may want the treemap to re-partition on changes of width/height rather than stay stable.

For now, it appears that the resolution is to either generate a new hierarchy instance or walk the existing hierarchy and clear out the _squarify caches.

Should internal nodes have (self) values?

Related #7. It’s possible to do this with a dummy node, but I’m not sure that’s a good idea. Does it really make sense for internal nodes to have value in a pack layout? There’s typically a lot of wasted space due to the enclosing circle having greater area than the sum of all children, so it’s not clear that visualizing this internal node value would be meaningful.

Improvements to circle-packing?

What if, at each step, we evaluated all possible positions along the front-chain based on the resulting smallest enclosing circle? Would that be too slow?

Re-implement stable (sticky) treemaps.

We should be able to generate stable layouts for either squarified or binary treemaps (and slice, dice, and sliceDice, but that’s trivial since those tiling methods are inherently stable). The stable update should be independent of the tiling method, since the relative positions of the cells are fixed for a stable update. Ideally, it could infer the adjacency of siblings by just looking at the previously-computed positions—then the tiling methods wouldn’t be required to explicitly enumerate the rows and their orientation.

Perhaps there should be a treemap.update method which recursively modifies the given root? Or, it could take a root, and then return a clone with the updated layout.

Report x0, x1 instead of x, dx?

This could help avoid inconsistencies due to rounding error, e.g., when a child exceeds the bounds of its parent (related d3/d3#2685):

d.parent.x + d.parent.dx // 0.26717557251908397
d.x + d.dx // 0.267175572519084

Automatically box non-hierarchy instances?

What if this:

var root = treemap(data);

Were equivalent to this:

var root = treemap(d3.hierarchy(data).sum(function(d) { return d.value; }));

You might even sort by default, like this?

var root = treemap(d3.hierarchy(data)
    .sum(function(d) { return d.value; })
    .sort(function(a, b) { return b.value - a.value; }));

And perhaps this:

var root = treemap(data, function(d) { return d.size; });

Could be equivalent to this (sorting TBD):

var root = treemap(d3.hierarchy(data).sum(function(d) { return d.size; }));

Which is a bit like how the d3-array methods take value accessors. It would add a bit of code to each hierarchy layout, but it feels like it might be convenient for the common case… albeit less self-describing.

How to find a given node within a hierarchy/layout?

Back in d3 3.x, d3 would populate my nodes with hierarchical/layout data (fields like parent, x, y).

Therefore, if I had a rootNode, and an otherNode that was reachable from rootNode, I could access otherNode.parent, otherNode.x, etc.

With d3 4.x, d3 creates a hierarchyRootNode which contains the field parent, and whose data field contains my rootNode. Similarly, were I to search for it from hierarchyRootNode, I could find another hierarchy node whose data field points to my otherNode.

My question is: is there an existing way of obtaining that node? That is, given a data node, how can I best obtain its hierarchy container?

I am currently doing an inefficient:
const hierarchyOtherNode = hierarchyRootNode.descendants().find(d => d.data.id === otherNode.id)

Is there a simpler way to get around this?

how to create a tree with json data?

here is my code :

var svg = d3.select('#test');
var g = svg.append("g");
var root = null;
var tree = d3.tree().size([svg.height,svg.width]);
d3.json('orgTreeData.json',function(err,data){
    if(err){
        throw err.stack;
    }
    root = d3.hierarchy(data, function(d) {
        return d.children;
    });
    tree(root);
    var link = g.selectAll(".link")
            .data(root.descendants().slice(1))
            .enter().append("path")
            .attr("class", "link")
            .attr("d", function(d) {
                console.log("attr d",d);
                return "M" + d.y + "," + d.x
                        + "C" + (d.y + d.parent.y) / 2 + "," + d.x
                        + " " + (d.y + d.parent.y) / 2 + "," + d.parent.x
                        + " " + d.parent.y + "," + d.parent.x;
            });
//..........
});

`
the problem is each node 's x , y attribut is NaN.

Treemap Horizontal/Vertical Layout

Hi,
how can I set the horizontal or vertical layout for the treemap independent of the width/height ration?
I would like to create a wide treemap with the fields appearing underneath thus the labels are better readable.
Screenshot 1 (wider than higher) should be like Screenshot 2 (higher than wider).
screenshot 2016-06-29 21 40 08
screenshot 2016-06-29 21 40 56

Generalize stable treemaps.

Would it be possible to generalize the stable update of an existing treemap? Currently the squarify layout stores its arrangement in node._squarify, but it seems like it should be possible to infer the arrangement from the previous node positions, and simply rescale them to fit the new values.

Sorting breaks re-squarifying.

The squarified treemap layout hides metadata in node._squarify so that it can perform a stable update of a squarified layout. However, if node.sort is called in the interim, then the order of nodes change, breaking the meaning if node._squarify (which is currently one plus the index of the last node in the current row).

The desired behavior is that the squarified layout is remains stable even after sorting, effectively ignoring the sort. (The nodes would be reordered, but retain their relative positions.)

One way to fix this would be to store the rows as arrays of nodes rather than indexes, such that any reordering of the children does not affect the stored metadata.

Tests.

We need lots of tests.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.