Supergroup
Extends:
[http://sigfried.github.io/supergroup/ -- Tutorial and demo]
http://www.toptal.com/javascript/ultimate-in-memory-data-collection-manipulation-with-supergroup-js
usage examples at http://sigfried.github.io/blog/supergroup
Avaailable as _.supergroup, Underscore mixin
Class of grouped records masquerading as an array
A Supergroup
object is an array of Value
objects made by grouping
an array of json objects by some set of properties or functions performed
on those objects. Each Value
represents a single group. Think of it as
a SQL group by:
SELECT state, zipcode, count(*)
FROM addresses
GROUP BY state, zipcode
In Supergroup parlance: 'state' and 'zipcode' are dimensions; states
('Alabama', 'Alaska') and zipcodes (50032, 20002) are values, or,
rather, value keys; and count(*)
is an aggregation performed on the
group. In regular SQL the underlying records represented in a group are
not available, with Supergroup they are. So a Value
has a key
which
is the text or number or any javascript object used to form the group.
In a group of states, the key of each value would be a string
, for
zipdcodes it could be a number
. (In previous versions of Supergroup,
these were String
and Number
objects, but now they are string
literals or anything else returnable by a grouping function.)
Value
objects have a key
, and valueobj.valueOf()
will return that
key, and valueobj.toString()
will return the results of the default
toString method on that key. valueobj.records
is an array of the original
javascript objects included in the group represented by the key. And
valueobj.indexes
is an array of the positions of those records in the
original array.
Supergroup extends
Array
Array
values areValues
- properties:
- groupsmap: keys are the keys used to group Values, values are Values
- recsmap: keys are index into original records array, values are orig records
- methods:
- rawValues: returns keys from groupsmap
Values
- depth: same as the depth of its parentList (supergroup)
- children: array of child Values collected in a supergroup (whose
depth is one greater than the depth of this Value)
Static Method Summary
Static Public Methods | ||
public static |
makeRoot(name: *, depth: *, recs: *, dimName: *): * There are time when you want to give your supergroup tree an explicit root, like when creating hierarchies in D3. |
|
public static |
wholeListNumeric(groups: *): * |
Constructor Summary
Public Constructor | ||
public |
constructor(recs: Object[], dims: string[], dims: function[], opts: Object): Array of Values Constructor groups records and builds tree structure |
Member Summary
Public Members | ||
public |
dim: * |
|
public |
dimFunc: * |
|
public |
dimName: * |
|
public |
dimNames: * |
|
public |
dims: * |
|
public |
groupsMap: * |
|
public |
parent: * |
|
public |
recsMap: * |
|
public |
root: * |
Method Summary
Public Methods | ||
public |
aggregates(func: *, field: *, ret: *): * |
|
public |
asRootVal(name: *, dimName: *): * |
|
public |
d3NestEntries(): * |
|
public |
d3NestMap(): * |
|
public |
flattenTree(): * |
|
public |
getLookupMap(): * |
|
public |
leafNodes(level: *): * |
|
public |
lookup(query: *): * lookup a value in a list, or, if query is an array it is interpreted as a path down the group hierarchy |
|
public |
lookupMany(query: *): * |
|
public |
namePaths(opts: *): * |
|
public |
rawValues(): * |
|
public |
rootList(func: *): * |
|
public |
singleLookup(query: *): * |
|
public |
state(): * |
Static Public Methods
public static makeRoot(name: *, depth: *, recs: *, dimName: *): * source
There are time when you want to give your supergroup tree an explicit root, like when creating hierarchies in D3. In that case call supergroup like:
let root = makeRoot('Tree Top', 0, recs),
let sg = new Supergroup({parent=root, dims=['state','zipcode']});
Otherwise Supergroup will make its own fake root with depth -1 instead of depth 0;
Params:
Name | Type | Attribute | Description |
name | * | ||
depth | * | ||
recs | * | ||
dimName | * |
Return:
* |
public static wholeListNumeric(groups: *): * source
Params:
Name | Type | Attribute | Description |
groups | * |
Return:
* |
Public Constructors
public constructor(recs: Object[], dims: string[], dims: function[], opts: Object): Array of Values source
Constructor groups records and builds tree structure
Params:
Name | Type | Attribute | Description |
recs | Object[] | array of objects, raw data |
|
dims | string[] | property names to be used for grouping the raw objects |
|
dims | function[] | functions on raw objects that return any kind of object to be used for grouping. property names and functions can be mixed in dims array. For single-level grouping, a single property name or function can be used instead of an array. |
|
opts.dimNames | string[] |
|
array (or single value) of dim names of same length as dims. Property name dims are used as dimName by default. |
opts | Object |
|
options for configuring supergroup behavior. opts are forwarded to Value constructors and subgroup constructors. |
opts.excludeValues | Object[] |
|
to exlude specific group values |
opts.preListRecsHook | function |
|
run recs through this function before continuing processing currently unused |
opts.truncateBranchOnEmptyVal | function |
|
Return:
Array of Values | enhanced with all the List methods |
Public Members
public dim: * source
public dimFunc: * source
public dimName: * source
public dimNames: * source
public dims: * source
public groupsMap: * source
public parent: * source
public recsMap: * source
public root: * source
Public Methods
public aggregates(func: *, field: *, ret: *): * source
Params:
Name | Type | Attribute | Description |
func | * | ||
field | * | ||
ret | * |
Return:
* |
public asRootVal(name: *, dimName: *): * source
Params:
Name | Type | Attribute | Description |
name | * | ||
dimName | * |
Return:
* |
public lookup(query: *): * source
lookup a value in a list, or, if query is an array it is interpreted as a path down the group hierarchy
Params:
Name | Type | Attribute | Description |
query | * |
Return:
* |