Nest Transform

The nest transform generates a hierarchical (tree) data structure from input data objects, based on dividing children into groups based on distinct field values. Internally, this transform generates a set of tree node objects that can then be processed by tree layout methods such as tree, treemap, pack, and partition.

Example

View Source Export PNG Export SVG

Transform Parameters

Property	Type	Description
generate	Boolean	A boolean flag (default `false`) indicating if non-leaf nodes generated by this transform should be included in the output data stream. By default only the input data objects (leaf nodes) are included. If non-leaf nodes are included, be aware that they will have a different set of properties than the input objects: the generated internal nodes will include a `key` property corresponding to the values extracted using the keys transform parameter.
keys	Field[ ]	An array of data fields by which to organize the data objects into a tree. Data objects will first be grouped into siblings based on the values of the first field in the parameter array. The process then continues, creating an additional depth level for each provided field. If unspecified, all data objects will treated as a single set of sibling nodes.

Usage

{
  "type": "nest",
  "keys": ["job", "region"]
}

Builds a tree data structure from input data objects. Starting with a root node, a set of sibling groups are generated for each distinct value of the job field. Then, within each job, an additional set of sibling nodes are generated for each distinct value of the region field. Finally, all input data objects within that group are included as leaves.

For example, given this input data:

[
  {"id": "A", "job": "Doctor", "region": "East"},
  {"id": "B", "job": "Doctor", "region": "East"},
  {"id": "C", "job": "Lawyer", "region": "East"},
  {"id": "D", "job": "Lawyer", "region": "East"},
  {"id": "E", "job": "Doctor", "region": "West"},
  {"id": "F", "job": "Doctor", "region": "West"},
  {"id": "G", "job": "Lawyer", "region": "West"},
  {"id": "H", "job": "Lawyer", "region": "West"}
]

The resulting tree structure is:

                  /- East - [A, B]
       /- Doctor -
      /           \- West - [E, F]
Root -
      \           /- East - [C, D]
       \- Lawyer -
                  \- West - [G, H]

If the generate parameter is set to true, the output data stream will also include data objects for the generated internal nodes. In the example above, the output data stream is:

[
  // original input nodes
  {"id": "A", "job": "Doctor", "region": "East"},
  {"id": "B", "job": "Doctor", "region": "East"},
  {"id": "C", "job": "Lawyer", "region": "East"},
  {"id": "D", "job": "Lawyer", "region": "East"},
  {"id": "E", "job": "Doctor", "region": "West"},
  {"id": "F", "job": "Doctor", "region": "West"},
  {"id": "G", "job": "Lawyer", "region": "West"},
  {"id": "H", "job": "Lawyer", "region": "West"},

  // generated internal nodes
  // for the root node, key is undefined
  // values arrays contain nested groups of objects
  {"values": [ ... ] },
  {"key": "Doctor", "values": [ ... ]},
  {"key": "Lawyer", "values": [ ... ] },
  {"key": "East", "values": [ ... ]},
  {"key": "West", "values": [ ... ]},
  {"key": "East", "values": [ ... ]},
  {"key": "West", "values": [ ... ]}
]