supergroup

<!DOCTYPE html><html lang="en" class="two-column-layout"><head><title>index</title></head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0"><meta name="groc-relative-root" content=""><meta name="groc-document-path" content="index"><meta name="groc-project-path" content="supergroup.js"><link rel="stylesheet" type="text/css" media="all" href="assets/style.css"><script type="text/javascript" src="assets/behavior.js"></script><body><div id="meta"><div class="file-path">supergroup.js</div></div><div id="document"><div class="segment"><div class="comments "><div class="wrapper"><h1 id="supergroupjs">supergroup.js</h1> Author: <a href="http://sigfried.org">Sigfried Gold</a> License: <a href="http://sigfried.mit-license.org/">MIT</a> usage examples at <a href="http://sigfried.github.io/blog/supergroup">http://sigfried.github.io/blog/supergroup</a></div></div><div class="code"><div class="wrapper">; // jshint -W053 'use strict()'; if (typeof(require) !== "undefined") { // make it work in node or browsers or other contexts _ = require('underscore'); // otherwise assume it was included by html file require('underscore-unchained'); // adds unchain as an Underscore mixin require('1670507/underscoreAddon.js'); // adds mean, median, etc. as mixins } var supergroup = (function() { var e = {}; // local reference to supergroup namespace</div></div></div><div class="segment"><div class="comments doc-section"><div class="wrapper"> class List Native Array of groups with various added methods and properties. Methods described below.</div></div><div class="code"><div class="wrapper"> function List() {}</div></div></div><div class="segment"><div class="comments doc-section"><div class="wrapper"> class Value Supergroup Lists are composed of Values which are String or Number objects representing group values. Methods described below.</div></div><div class="code"><div class="wrapper"> function Value() {}</div></div></div><div class="segment"><div class="comments doc-section"><div class="wrapper"> exported function supergroup.group(recs, dim, opts) Parameters: <ul> <li>recs must be an Array of Objects. (list of records to be grouped)</li> <li>dim must be a string or Function. (either the property name to group by or a function returning a group by string or number)</li> <li>opts is optional and must be an Object. <ul><li>opts.childProp must be a String and has a default value of 'children'. (If group ends up being hierarchical, this will be the property name of any children)</li> <li>opts.excludeValues is optional and must be an Array of Strings. (to exlude specific group values)</li> <li>opts.preListRecsHook is optional and must be a function. (run recs through this function before continuing processing)</li> <li>opts.dimName is optional and must be a function. (defaults to the value of <code>dim</code>. If <code>dim</code> is a function, the dimName will be ugly.)</li></ul></li> </ul> Returns an Array of Values (enhanced with all the List methods Avaailable as _.supergroup, Underscore mixin)</div></div><div class="code"><div class="wrapper"> e.group = function(recs, dim, opts) { if (_(dim).isArray()) return e.multiDimList(recs, dim, opts); // handoff to multiDimmList if dim is an array opts = opts || {}; recs = opts.preListRecsHook ? opts.preListRecsHook(recs) : recs; childProp = opts.childProp || childProp; var groups = _.groupBy(recs, dim); // use Underscore's groupBy: http://underscorejs.org/#groupBy if (opts.excludeValues) { _(opts.excludeValues).each(function(d) { delete groups[d]; }); } var isNumeric = wholeListNumeric(groups); // does every group Value look like a number or a missing value? var groups = _.map(_.pairs(groups), function(pair, i) { // setup Values for each group in List var rawVal = pair[0]; var val; if(isNumeric) { val = makeNumberValue(rawVal); // either everything's a Number } else { val = makeStringValue(rawVal); // or everything's a String }</div></div></div><div class="segment"><div class="comments "><div class="wrapper">The original records in this group are stored as an Array in the records property (should probably be a getter method).</div></div><div class="code"><div class="wrapper"> val.records = pair[1];</div></div></div><div class="segment"><div class="comments "><div class="wrapper">val.records is enhanced with Underscore methods for convenience, but also with the supergroup method that's been mixed in to Underscore. So you can group this specific subset like: val.records.supergroup on FIX!!!!!!</div></div><div class="code"><div class="wrapper"> _.unchain(val.records); val.dim = (opts.dimName) ? opts.dimName : dim; val.records.parentVal = val; // NOT TESTED, NOT USED, PROBABLY WRONG if (opts.parent) val.parent = opts.parent; if (val.parent) { if ('depth' in val.parent) { val.depth = val.parent.depth + 1; } else { val.parent.depth = 0; val.depth = 1; } } else { val.depth = 0; } return val; }); groups = makeList(groups); groups.records = recs; // NOT TESTED, NOT USED, PROBABLY WRONG groups.dim = (opts.dimName) ? opts.dimName : dim; groups.isNumeric = isNumeric; _(groups).each(function(group) { group.parentList = groups; });</div></div></div><div class="segment"><div class="comments "><div class="wrapper">pointless without recursion</div></div><div class="code"><div class="wrapper"> //if (opts.postListListHook) groups = opts.postListListHook(groups); return groups; }; e.multiDimList = function(recs, dims, opts) { var groups = e.group(recs, dims[0], opts); _.chain(dims).rest().each(function(dim) { groups.addLevel(dim, opts); }); return groups; }; List.prototype.asRootVal = function(name, dimName) { name = name || 'Root'; var val = makeValue(name); val.records = this; // is this wrong? val[childProp]= this; val.descendants().each(function(d) { d.depth = d.depth + 1; }); val.depth = 0; val.dim = dimName || 'root'; return val; }; List.prototype.leafNodes = function(level) { return this.invoke('leafNodes').flatten(); }; List.prototype.rawValues = function() { return _(this).map(function(d) { return d.toString(); }); }; List.prototype.lookup = function(query) { if (_.isArray(query)) {</div></div></div><div class="segment"><div class="comments "><div class="wrapper">if group has children, can search down the tree</div></div><div class="code"><div class="wrapper"> var values = query.slice(0); var list = this; var ret; while(values.length) { ret = list.singleLookup(values.shift()); list = ret[childProp]; } return ret; } else { return this.singleLookup(query); } }; List.prototype.singleLookup = function(query) { var that = this; if (! ('lookupMap' in this)) { this.lookupMap = {}; this.forEach(function(d) { that.lookupMap[d] = d; }); } if (query in this.lookupMap) return this.lookupMap[query]; }; List.prototype.flattenTree = function() { return _.chain(this) .map(function(d) { var desc = d.descendants(); return [d].concat(desc); }) .flatten() .filter(_.identity) // expunge nulls .tap(e.addListMethods) .value(); }; List.prototype.addLevel = function(dim, opts) { _(this).each(function(val) { val.addLevel(dim, opts); }); }; function makeList(arr_arg) { var arr = [ ]; arr.push.apply(arr, arr_arg); //arr.__proto__ = List.prototype; for(var method in List.prototype) { Object.defineProperty(arr, method, { value: List.prototype[method] }); } _.unchain(arr); return arr; }</div></div></div><div class="segment"><div class="comments doc-section"><div class="wrapper"> memberof enlightenedData <pre><code>e.addUnderscoreMethods = function(arr) { _(e.underscoreMethodsToAddToArrays).each(function(methodName) { if (_(arr).has(methodName)) return; Object.defineProperty(arr, methodName, { value: function() { var part = _.partial(_[methodName], arr); var result = part.apply(null, _.toArray(arguments)); if (_.isArray(result)) e.addListMethods(result); return result; }}); }); return arr; }; e.underscoreMethodsToAddToArrays = [ "each", "map", "reduce", "find", "filter", "reject", "all", "every", "any", "some", "contains", "invoke", "pluck", "where", "findWhere", "max", "min", "shuffle", "sortBy", "groupBy", "countBy", "sortedIndex", "size", "first", "initial", "last", "rest", "compact", "flatten", "without", "uniq", "union", "intersection", "difference", "zip", "unzip", //"object", "indexOf", "lastIndexOf", "chain", "result" ]; </code></pre> Enhance arrays with {@link http://underscorejs.org/ Underscore} functions that work on arrays. Parameters: <ul> <li>arr must be an Array.</li> </ul> Returns an Array (now enhanced Now can call Underscore functions as methods on the array, and if the return value is an array, it will also be enhanced.) and Returns a whatever the underscore function would return Example: `enlightenedData.addUnderscoreMethods(['a','bb','ccc']) .pluck('length') . group.where({foo:bar}).invoke('baz')</div></div><div class="code"><div class="wrapper"> function makeValue(v_arg) { if (isNaN(v_arg)) { return makeStringValue(v_arg); } else { return makeNumberValue(v_arg); } } function StringValue() {} //StringValue.prototype = new String; function makeStringValue(s_arg) { var S = new String(s_arg); //S.__proto__ = StringValue.prototype; // won't work in IE10 for(var method in StringValue.prototype) { Object.defineProperty(S, method, { value: StringValue.prototype[method] }); } return S; } function NumberValue() {} //NumberValue.prototype = new Number; function makeNumberValue(n_arg) { var N = new Number(n_arg); //N.__proto__ = NumberValue.prototype; for(var method in NumberValue.prototype) { Object.defineProperty(N, method, { value: NumberValue.prototype[method] }); } return N; } function wholeListNumeric(groups) { var isNumeric = _.every(_.keys(groups), function(k) { return k === null || k === undefined || (!isNaN(Number(k))) || ["null", ".", "undefined"].indexOf(k.toLowerCase()) > -1; }); if (isNumeric) { _.each(_.keys(groups), function(k) { if (isNaN(k)) { delete groups[k]; // getting rid of NULL values in dim list!! } }); } return isNumeric; } var childProp = 'children'; Value.prototype.extendGroupBy = // backward compatibility Value.prototype.addLevel = function(dim, opts) { opts = opts || {}; _.each(this.leafNodes(), function(d) { opts.parent = d; if (d.in && d.in === "both") { d[childProp] = e.diffList(d.from, d.to, dim, opts); } else { d[childProp] = e.group(d.records, dim, opts); if (d.in ) { _(d[childProp]).each(function(c) { c.in = d.in; c[d.in] = d[d.in]; }); } } d[childProp].parentVal = d; // NOT TESTED, NOT USED, PROBABLY WRONG!!! }); }; Value.prototype.leafNodes = function(level) { var ret = [this]; if (typeof level === "undefined") { level = Infinity; } if (level !== 0 && this[childProp] && (!level || this.depth < level)) { ret = _.flatten(_.map(this[childProp], function(c) { return c.leafNodes(level); }), true); } return makeList(ret); };</div></div></div><div class="segment"><div class="comments "><div class="wrapper">didn't make this yet, just copied from above Value.prototype.descendants = function(level) { var ret = [this]; if (level !== 0 && this[childProp] && (!level || this.depth < level)) ret = .flatten(.map(this[childProp], function(c) { return c.leafNodes(level); }), true); return makeList(ret); };</div></div><div class="code"><div class="wrapper"> function delimOpts(opts) { if (typeof opts === "string") opts = {delim: opts}; opts = opts || {}; if (!_(opts).has('delim')) opts.delim = '/'; return opts; } Value.prototype.dimPath = function(opts) { opts = delimOpts(opts); opts.dimName = true; return this.namePath(opts); }; Value.prototype.namePath = function(opts) { opts = delimOpts(opts); var path = this.pedigree(opts); if (opts.noRoot) path.shift(); if (opts.backwards || this.backwards) path.</sp