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.

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 have 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.
key Field A data field containing a unique key (identifier) for each node. If not specified, Vega will use internal data object ids.

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, new data objects with the following structure will be generated:

[
  {}, // root, key is undefined
  {"key": "Doctor"},
  {"key": "Lawyer"},
  {"key": "East"},
  {"key": "West"},
  {"key": "East"},
  {"key": "West"}
]