Class pv.Nest
Represents a Nest operator for the specified array. Nesting allows elements in an array to be grouped into a hierarchical tree structure. The levels in the tree are specified by key functions. The leaf nodes of the tree can be sorted by value, while the internal nodes can be sorted by key. Finally, the tree can be returned either has a multidimensional array via #entries, or as a hierarchical map via #map. The #rollup routine similarly returns a map, collapsing the elements in each leaf node using a summary function.
For example, consider the following tabular data structure of Barley yields, from various sites in Minnesota during 1931-2:
{ yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm" }, { yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca" }, { yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris" }, ...To facilitate visualization, it may be useful to nest the elements first by year, and then by variety, as follows:
var nest = pv.nest(yields) .key(function(d) d.year) .key(function(d) d.variety) .entries();This returns a nested array. Each element of the outer array is a key-values pair, listing the values for each distinct key:
{ key: 1931, values: [ { key: "Manchuria", values: [ { yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm" }, { yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca" }, { yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris" }, ... ] }, { key: "Glabron", values: [ { yield: 43.07, variety: "Glabron", year: 1931, site: "University Farm" }, { yield: 55.20, variety: "Glabron", year: 1931, site: "Waseca" }, ... ] }, ] }, { key: 1932, values: ... }Further details, including sorting and rollup, is provided below on the corresponding methods.
Defined in: Nest.js.
Constructor Attributes | Constructor Name and Description |
---|---|
pv.Nest(array)
Constructs a nest operator for the specified array.
|
Method Attributes | Method Name and Description |
---|---|
entries()
Returns a hierarchical nested array.
|
|
key(key)
Nests using the specified key function.
|
|
map()
Returns a hierarchical map of values.
|
|
rollup(f)
Returns a rollup map.
|
|
sortKeys(order)
Sorts the previously-added keys.
|
|
sortValues(order)
Sorts the leaf values.
|
- Parameters:
- {array} array
- an array of elements to nest.
For an example usage, see the Nest constructor.
- Returns:
- a hierarchical nested array.
- Parameters:
- {function} key
- a key function; must return a string or suitable map key.
- Returns:
- {pv.Nest} this.
pv.nest(yields) .key(function(d) d.variety) .key(function(d) d.site) .map()returns a map m such that m[variety][site] is an array, a subset of yields, with each element having the given variety and site.
- Returns:
- a hierarchical map of values.
pv.nest(yields) .key(function(d) d.site) .rollup(function(v) pv.median(v, function(d) d.yield))first groups yield data by site, and then returns a map from site to median yield for the given site.
- Parameters:
- {function} f
- a rollup function.
- Returns:
- a hierarchical map, with the leaf values computed by f.
- See:
- #map
pv.nest(yields) .key(function(d) d.year) .key(function(d) d.variety) .sortKeys() .entries()groups yield data by year, then variety, and sorts the variety groups lexicographically (since the variety attribute is a string).
Key sort order is only used in conjunction with #entries, which returns an array of key-values pairs. If the nest is used to construct a #map instead, keys are unsorted.
- Parameters:
- {function} order Optional
- an optional comparator function.
- Returns:
- {pv.Nest} this.
pv.nest(yields) .key(function(d) d.year) .key(function(d) d.variety) .sortValues(function(a, b) a.yield - b.yield) .entries()groups yield data by year, then variety, and sorts the values for each variety group by yield.
Value sort order, unlike keys, applies to both #entries and #map. It has no effect on #rollup.
- Parameters:
- {function} order Optional
- an optional comparator function.
- Returns:
- {pv.Nest} this.