…

If you use NPM, npm install d3-hierarchy. Otherwise, download the latest release.

• Hierarchy
• Treemap
• Partition
• Pack

Before you can compute a hierarchical layout, you need a hierarchical data structure. If you already have hierarchical data, such as a JSON file, you can pass it directly to the hierarchical layout. Otherwise, you can rearrange tabular input data, such as a comma-separated values (CSV) file, into a hierarchy using d3.hierarchy.

For example, consider the following table of relationships:

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

id,parentId
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:

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

To convert to a hierarchy:

var root = d3.hierarchy()(table);

This returns:

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

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

# d3.hierarchy()

Constructs a new hierarchy generator with the default settings.

# hierarchy(data)

Generates a new hierarchy from the specified tabular data. Each node in the returned object has a shallow copy of the properties from the corresponding data object, excluding the following reserved properties: id, parentId, children.

# hierarchy.id([id])

If id is specified, sets the id accessor to the given function and returns this hierarchy generator. 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 generator, 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.)

# hierarchy.parentId([parentId])

If parentId is specified, sets the parent id accessor to the given function and returns this hierarchy generator. 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 generator, 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.

# d3.hierarchyNode(data)

Constructs a root node from the specified hierarchical data. The specified data must be an object representing the root node, and may have a data.children property specifying an array of data representing the children of the root node; each descendant child data may also have data.children. See Hierarchy for an example.

This method is typically not called directly; instead it is used by hierarchical layouts to construct root nodes. You can also use it to test whether an object is an instanceof d3.hierarchyNode, or to extend the node prototype.

# node.data

A reference to the data associated with this node, as specified to the constructor.

# node.depth

The depth of the node: zero for the root node, and increasing by one for each subsequent generation.

# node.parent

A reference to the parent node; null for the root node.

# node.children

An array of child nodes, if any; undefined for leaf nodes.

# node.ancestors()

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

# node.descendants()

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

# node.leaves()

Returns the array of leaf nodes; a subset of this node’s descendants including only nodes with no children.

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 the “slice-and-dice” method, which simply alternates between horizontal and vertical subdivision by depth.

# d3.treemap()

…

# treemap(data)

…

# treemap.update(root)

…

# treemap.tile([tile])

…

# treemap.value([value])

…

# treemap.sort([sort])

…

# treemap.size([size])

…

# treemap.round([round])

…

# treemap.padding([padding])

…

# treemap.paddingInner([padding])

…

# treemap.paddingOuter([padding])

…

…

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

…

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

…

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

…

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

…

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

…

# squarify.ratio(ratio)

…

…

# d3.partition()

…

# partition(data)

…

# partition.value([value])

…

# partition.sort([sort])

…

# partition.size([size])

…

# partition.round([round])

…

# partition.padding([padding])

…

…

# d3.pack()

…

# pack(data)

…

# pack.radius([radius])

…

# pack.value([value])

…

# pack.sort([sort])

…

# pack.size([size])

…

# pack.padding([padding])

…