jupyter-ijavascript-utils 1.32.0 → 1.35.0

package/DOCS.md

@@ -75,6 +75,9 @@ Give it a try here:
 
 ## What's New
 
+* 1.35 - {@link module:object.extractObjectProperties|extractObjectProperties} / {@link module:object.extractObjectProperty|extractObjectProperty} - to do horizontal transposes on objects
+* 1.34 - {@link module:format.mapArrayDomain|format.mapArrayDomain} and add notes in the header of {@link module:random|random} on using non-uniform distributions.
+* 1.33 - Object.augmentInherit and Object.union
 * 1.32 - Array.indexify to identify sections within a 1d array into a hierarchy.
 * 1.31 - harden Array.transpose for arrays with nulls, and Table.generateTSV
 * 1.30 - add Format.wordWrap and Format.lineCount

package/Dockerfile

@@ -1,3 +1,3 @@
 # syntax=docker/dockerfile:1
 
-FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.32.0
+FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.35.0

package/README.md

@@ -55,6 +55,9 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 # What's New
 
+* 1.35 - object.extractObjectProperties / object.extractObjectProperty - to do horizontal transposes on objects
+* 1.34 - format.mapArrayDomain and add notes in to random on using non-uniform distributions.
+* 1.33 - Object.augmentInherit and Object.union
 * 1.32 - Array.indexify to identify sections within a 1d array into a hierarchy.
 * 1.31 - harden Array.transpose for arrays with nulls, and Table.generateTSV
 * 1.30 - add Format.wordWrap and Format.lineCount

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.32.0",
+  "version": "1.35.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",

package/src/aggregate.js

@@ -502,6 +502,7 @@ module.exports.unique = function unique(collection, accessor, uniquifierFn) {
 
   return Array.from(new Set(
     collection.map(cleanedFunc)
+      .reduce((result, val) => (val instanceof Set || Array.isArray(val)) ? [...result, ...val] : [...result, val], [])
   ));
 };
 

package/src/array.js

@@ -639,6 +639,11 @@ module.exports.arangeMulti = module.exports.arrangeMulti;
  * //   }
  * // ];
  * ```
+ * 
+ * @param {Array} source - list of values to index
+ * @param {...Function} sectionIndicatorFunctions - each function indicates a new section
+ * @returns {Object[]} - collection of objects, each with a new section (indicating the layers) 
+ *            and subIndex: unique value in the section (always 0 for header)
  */
 module.exports.indexify = function indexify(source, ...sectionIndicatorFunctions) {
   const functionSignature = 'indexify(source, ...sectionIndicatorFunctions)';

package/src/format.js

@@ -24,6 +24,7 @@
  *   * {@link module:format.millisecondDuration|format.millisecondDuration}
  * * Mapping Values
  *   * {@link module:format.mapDomain|format.mapDomain} - projects a value from a domain of expected values to a range of output values, ex: 10% of 2 Pi
+ *   * {@link module:format.mapArrayDomain|format.mapArrayDomain} - projects a value from between a range a value, and picks the corresponding value from an array
  * * Identifying Time Periods
  *   * {@link module:format.timePeriod|format.timePeriod} - Converts a time to a time period, very helpful for animations
  *   * {@link module:format.timePeriodPercent|format.timePeriodPercent} - Determines the percent complete of the current time period
@@ -383,6 +384,112 @@ module.exports.mapDomain = function mapDomain(val, [domainMin, domainMax], [rang
   return (((val - domainMin) * (rangeMax - rangeMin)) / (domainMax - domainMin)) + rangeMin;
 };
 
+/**
+ * projects a value from a domain of expected values to an array - very useful for random distributions.
+ * 
+ * like mapping normal / gaussian distributions to an array of values with 
+ * [d3-random](https://observablehq.com/@d3/d3-random)
+ * as format.mapArrayDomain projects a value from between a range a value,
+ * and picks the corresponding value from an array.
+ * 
+ * For example:
+ * 
+ * ```
+ * require('esm-hook');
+ * d3 = require('d3');
+ * 
+ * //-- create a number generator using Normal / Gaussian distribution
+ * randomGenerator = d3.randomNormal(
+ *  0.5, // mu - or centerline
+ *  0.1 // sigma - or spread of values
+ * );
+ * 
+ * randomValue = randomGenerator();
+ * // randomValue - 0.4
+ * 
+ * randomDataset = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'];
+ * 
+ * //-- create an array of 3 items, each with the results from randomGenerator
+ * results = utils.array.size(3, () => randomGenerator());
+ * // [ 0.6235937672428706, 0.4991359903898883, 0.4279365561645624 ]
+ * 
+ * //-- map those values to the randomDataset
+ * results.map(val => ({ pick: utils.format.mapArrayDomain(val, randomDataset) }));
+ * // [ { pick: 'g' }, { pick: 'e' }, { pick: 'e' } ]
+ * 
+ * //-- group them by the pick field
+ * //-- then add a new property called count - using the # of records with the same value
+ * groupedResults = utils.group.by(resultPicks, 'pick')
+ *     .reduce((list) => ({ count: list.length }));
+ * // [ { pick: 'g', count: 1 }, { pick: 'e', count: 2 } ]
+ * 
+ * //-- make a bar chart (only with 10k results)
+ * utils.vega.embed((vl) => {
+ *     return vl
+ *       .markBar()
+ *       .title('Distribution')
+ *       .data(groupedResults)
+ *       .encode(
+ *         vl.x().fieldN('value'),
+ *         vl.y().fieldQ('count').scale({type: 'log'})
+ *       );
+ * });
+ * ```
+ * ![Screenshot of the chart above](img/randomMap_normalDistribution.png)
+ * 
+ * @param {Number} val - value to be mapped
+ * @param {Array} targetArray - array of values to pick from
+ * @param {Array} domain - [min, max] - domain of possible input values
+ * @param {Array} [domain.domainMin = 0] - minimum input value (anything at or below maps to rangeMin)
+ * @param {Array} [domain.domainMax = 1] - maximum input value (anything at or above maps to rangeMax)
+ * @returns Number
+ * @see {@link module:format.clampDomain|clampDomain(value, [min, max])}
+ * @example
+ * 
+ * //-- array of 10 values
+ * randomArray = ['a', 'b', 'c', 'd', 'e'];
+ * 
+ * format.mapArrayDomain(-1, randomArray, [0, 5]);
+ * // 'a'  - since it is below the minimum value
+ * format.mapArrayDomain(6, randomArray, [0, 5]);
+ * // 'e'   - since it is the minimum value
+ * 
+ * format.mapArrayDomain(0.9, randomArray, [0, 5]);
+ * // 'a'
+ * format.mapArrayDomain(1, randomArray, [0, 5]);
+ * // 'b'
+ * format.mapArrayDomain(2.5, randomArray, [0, 5]);
+ * // 'c' 
+ * 
+ * //-- or leaving the domain of possible values value can be out:
+ * format.mapArrayDomain(0.5, randomArray); // assumed [0, 1]
+ * // 'c'
+ */
+module.exports.mapArrayDomain = function mapArrayDomain(val, targetArray, domain = null) {
+  if (!targetArray || !Array.isArray(targetArray)) {
+    throw Error('mapArrayDomain: targetArray is not an array');
+  } else if (targetArray.length < 1) {
+    throw Error('mapArrayDomain: targetArray is not a populated array');
+  }
+
+  const cleanArray = domain || [];
+  const [domainMin = 0, domainMax = 1] = cleanArray;
+
+  if (val <= domainMin) {
+    return targetArray[0];
+  } else if (val >= domainMax) {
+    return targetArray[targetArray.length - 1];
+  }
+
+  const targetIndex = Math.floor(FormatUtils.mapDomain(
+    val,
+    [domainMin, domainMax],
+    [0, targetArray.length]
+  ));
+  // console.log(targetIndex);
+  return targetArray[targetIndex];
+};
+
 /**
  * Given that a period of time is millisecondPeriod number of milliseconds long,
  * determines which period of time we are currently in (timeEpoch / millisecondPeriod)

package/src/object.js

@@ -16,18 +16,23 @@ const FormatUtils = require('./format');
  *   * {@link module:object.setPropertyDefaults|setPropertyDefaults()} - sets values for objects that don't currently have the property
  *   * {@link module:object.propertyValueSample|propertyValueSample(collection)} - finds non-empty values for all properties found in the collection
  * * Manipulating objects
- *   * {@link module:object.objAssign|objAssign()} -
- *   * {@link module:object.objAssignEntities|objAssignEntities()} -
+ *   * {@link module:object.assign|objAssign(object, property, value)} - Applies properties to an object in functional programming style.
+ *   * {@link module:object.assignEntities|objAssignEntities(object, [property, value])} - Applies properties to an object using Array values - [key,value]
+ *   * {@link module:object.augment|augment(object, augmentFn)} - Applies properties to an object similar to Map
+ *   * {@link module:object.augmentInherit|augmentInherit(object, augmentFn)} - Applies properties to a collection of objects, 'remembering' the last value - useful for 1d to *D lists.
  *   * {@link module:object.selectObjectProperties|selectObjectProperties()} - keep only specific properties
  *   * {@link module:object.filterObjectProperties|filterObjectProperties()} - remove specific properties
  *   * {@link module:object.mapProperties|mapProperties(collection, fn, ...properties)} - map multiple properties at once (like parseInt, or toString)
  *   * {@link module:object.formatProperties|formatProperties(collection, propertyTranslation)} - map specific properties (ex: toString, toNumber, etc)
+ *   * {@link module:object.union|union(objectList1, objectList2)} - Unites the properties of two collections of objects.
  * * Fetch child properties from related objects
  *   * {@link module:object.fetchObjectProperty|fetchObjectProperty(object, string)} - use dot notation to bring a child property onto a parent
  *   * {@link module:object.fetchObjectProperties|fetchObjectProperties(object, string[])} - use dot notation to bring multiple child properties onto a parent
  *   * {@link module:object.join|join(array, index, map, fn)} - join a collection against a map by a given index
  *   * {@link module:object.joinProperties|join(array, index, map, ...fields)} - join a collection, and copy properties over from the mapped object.
  *   * {@link module:object.propertyFromList|propertyFromList(array, propertyName)} - fetches a specific property from all objects in a list
+ *   * {@link module:object.extractObjectProperty|extractObjectProperty(list, propertyNameOrFn)} - extracts a property or fn across all objects in list.
+ *   * {@link module:object.extractObjectProperties|extractObjectProperties(list, propertyNameOrFnMap)} - extracts multiple propertie or fn across all objects in list.
  * * Rename properties
  *   * {@link module:object.cleanProperties|cleanProperties()} - correct inaccessible property names in a list of objects - in place
  *  *   * {@link module:object.cleanProperties2|cleanProperties2()} - correct inaccessible property names in a list of objects - on a cloned list
@@ -533,6 +538,100 @@ module.exports.fetchObjectProperties = function fetchObjectProperties(list, prop
   });
 };
 
+/**
+ * Similar to a transpose, this finds all the values of a particular property
+ * within a list of objects.
+ * 
+ * ```
+ * weather = [
+ *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ *   null,
+ *   { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
+ *   { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }
+ * ];
+ * 
+ * utils.object.extractObjectProperty(weather, 'city');
+ * // [ 'Seattle', 'New York', 'Chicago'];
+ * ```
+ * 
+ * @param {Object|Object[]} objectList - list of objects to extract the property from
+ * @param {Function | String} propertyOrFn - Name of the property or accessor function
+ * @returns {Array} - single array the values stored in propertyOrFn across all objects in objectList.
+ * @see {@link module:aggregate.unique|unique()} to see all the unique values stored
+ * @see {@link module:object.extractObjectProperties|extractObjectProperties(list, propertyNameOrFnMap)} to see the values extracted into a single object / horizontal transpose.
+ */
+module.exports.extractObjectProperty = function extractObjectProperty(list, propertyOrFn) {
+  let cleanList = !list ? [] : Array.isArray(list) ? list : [list];
+  cleanList = cleanList.filter((r) => r);
+  const fn = ObjectUtils.evaluateFunctionOrProperty(propertyOrFn);
+  return cleanList.map(fn);
+};
+
+/**
+ * Similar to a transpose, this finds all the values of a particular property
+ * within a list of objects.
+ * 
+ * ```
+ * weather = [
+ *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+ *   null,
+ *   { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
+ *   { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 }
+ * ];
+ * 
+ * utils.object.extractObjectProperties(weather, ['city', 'month']);
+ * // { city: [ 'Seattle', 'New York', 'Chicago'], month: ['Aug', 'Apr', 'Apr'] }
+ * 
+ * // note you can also pass maps with property name strings, or functions.
+ * extractionMap = new Map();
+ * extractionMap.set('city', null); // default the property by the key name
+ * extractionMap.set('city2', 'city'); // specify the property to use
+ * extractionMap.set('city3', (r) => r.city); // specify a function
+ * 
+ * utils.object.extractObjectProperties(weather, extractionMap);
+ * // {
+ * //   city: ['Seattle', 'New York', 'Chicago'],
+ * //   city2: ['Seattle', 'New York', 'Chicago'],
+ * //   city3: ['Seattle', 'New York', 'Chicago']
+ * // };
+ * ```
+ * 
+ * @param {Object|Object[]} objectList - list of objects to extract the property from
+ * @param {Map<Function | String>} propertyOrFnMap - Name of the property or accessor function
+ * @returns {Object} - Object with the keys in the map as properties - extracting the values across all in list.
+ * @see {@link module:object.extractObjectProperty|extractObjectProperty(list, propertyNameOrFn)} to see all the values stored for a single property.
+ */
+module.exports.extractObjectProperties = function extractObjectProperties(list, propertyOrFnMap) {
+  let propertyEntries = [];
+  const signature = 'object.extractObjectProperties(list:Object[], propertyOrFnMap:Map<String, stringOrFn>)';
+
+  if (!propertyOrFnMap) {
+    return [];
+  } else if (Array.isArray(propertyOrFnMap)) {
+    for (let i = 0; i < propertyOrFnMap.length; i += 1) {
+      const propertyOrFnKey = propertyOrFnMap[i];
+
+      //-- only string properties are accepted as an array
+      if (typeof propertyOrFnKey === 'string') {
+        propertyEntries.push([propertyOrFnKey, propertyOrFnKey]);
+      }
+    }
+  } else if (propertyOrFnMap instanceof Map) {
+    propertyEntries = [...propertyOrFnMap.entries()];
+  } else {
+    throw Error(`${signature}: propertyOrFnMap must be a map of propertyName keys, with a function or property name as the value`);
+  }
+
+  const results = {};
+  propertyEntries.forEach(([propertyName, propertyOrFn]) => {
+    results[propertyName] = ObjectUtils.extractObjectProperty(list, propertyOrFn || propertyName);
+    // const fn = ObjectUtils.evaluateFunctionOrProperty(propertyOrFn);
+    // results[propertyName] = cleanList.map(fn);
+  });
+
+  return results;
+};
+
 /**
  * Accesses a property using a string
  * @param {Object} obj - object to access the properties on
@@ -1129,3 +1228,186 @@ module.exports.propertyValueSample = function propertyValueSample(objCollection)
 
   return result;
 };
+
+/**
+ * Appends values to a collection of objects,
+ * where if the value `undefined` is provided, 
+ * then it "remembers" or "inherits" the value previously used.
+ * 
+ * This is VERY useful for converting a 1 dimensional list, into a hierarchical tree structure.
+ * 
+ * For example, say we got this from a previous successful scrape:
+ * 
+ * ```
+ * source = [
+ *   { text: '# Overview' },
+ *   { text: 'This entire list is a hierarchy of data.' },
+ *   { text: '# Section A' },
+ *   { text: 'This describes section A' },
+ *   { text: '## SubSection 1' },
+ *   { text: 'With a subsection belonging to Section A' },
+ *   { text: '# Section B' },
+ *   { text: 'With an entirely unrelated section B, that is sibling to Section A' }
+ * ];
+ * ```
+ * 
+ * We would like to know which heading1 and heading2 the texts belong to:
+ * 
+ * ```
+ * 
+ * const isHeader1 = (str) => str.startsWith('# ');
+ * const isHeader2 = (str) => str.startsWith('## ');
+ * 
+ * //-- note, return undefined for any property you don't want to have inherited.
+ * inheritFn = (entry) => ({
+ *   section: isHeader1(entry.text) ? entry.text.replace(/#+\s+/, '') : undefined,
+ *   subSection: isHeader2(entry.text) ? entry.text.replace(/#+\s+/, '') : undefined
+ * });
+ * 
+ * results = utils.object.augmentInherit(source, inheritFn);
+ * ```
+ * 
+ * text                                                              |section  |subSection  
+ * --                                                                |--       |--          
+ * Overview                                                          |Overview |undefined            
+ * This entire list is a hierarchy of data.                          |Overview |undefined   
+ * Section A                                                         |Section A|undefined   
+ * This describes section A                                          |Section A|undefined   
+ * SubSection 1                                                      |Section A|SubSection 1
+ * With a subsection belonging to Section A                          |Section A|SubSection 1
+ * Section B                                                         |Section B|undefined   
+ * With an entirely unrelated section B, that is sibling to Section A|Section B|undefined   
+ * SubSection 1                                                      |Section B|SubSection 1
+ * And another subsection 1, but this time related to Section B.     |Section B|SubSection 1
+ * 
+ * So we pass the collection of results as the source, and an augment function,
+ * that returns the heading 1 value - that is then kept until the next heading 1.
+ * (Similar for subSection using heading 2)
+ * 
+ * @param {Object[]} source - the collection of objects to check and augment.
+ * @param {Function} augmentFn - function accepting each entry, and returning the properties to "inherit" <br /> or a property with a value of undefined - if it should not be preserved.
+ * @returns {Object[]} - new version of the source objects with the properties applied.
+ * 
+ *  @see {@link module:object.augment|augment()} - Applies properties to an object similar to Map
+ */
+module.exports.augmentInherit = function augmentInherit(source, augmentFn) {
+  const signature = 'augmentInherit(source, augmentFn)';
+  if (!Array.isArray(source)) {
+    throw new Error(`${signature}: source must be an array`);
+  } else if (typeof augmentFn !== 'function') {
+    throw new Error(`${signature}: augmentFn must be a function of signature: (entry, lastValue) => obj`);
+  }
+
+  let keys;
+
+  let lastValue = {};
+  return source.map((entry, index) => {
+    const fnResult = augmentFn(entry, lastValue);
+
+    //-- ignore all values that are undefined
+    const newValue = { ...lastValue };
+    let isFlipped = false;
+    keys = Object.keys(fnResult || {});
+    keys.forEach((key) => {
+      if (isFlipped) {
+        newValue[key] = undefined;
+      } else if (fnResult[key] !== undefined) {
+        newValue[key] = fnResult[key];
+        isFlipped = true;
+      }
+    });
+
+    // console.log(`index:${index}: entry:${JSON.stringify(entry)}, newValue:${JSON.stringify(newValue)}, lastValue:${JSON.stringify(lastValue)}`)
+    const result = ({ ...entry, ...newValue });
+    lastValue = newValue;
+    return result;
+  });
+};
+
+/**
+ * Unites the properties of two collections of objects.
+ * 
+ * For example:
+ * 
+ * ```
+ * source1 = [
+ *  { first: 'john' },
+ *  { first: 'jane' }
+ * ];
+ * source2 = [
+ *  { last: 'doe' },
+ *  { last: 'dough' }
+ * ];
+ * utils.object.union(source1, source2);
+ * // [{ first: 'john', last: 'doe' },
+ * //  { first: 'jane', last: 'dough' }];
+ * ```
+ * 
+ * Note that you can also pass a single object, to have it union to multiple.
+ * 
+ * ```
+ * source1 = [
+ *  { first: 'john' },
+ *  { first: 'jane' }
+ * ];
+ * //-- same object to be applied to all
+ * source2 = { last: 'doe' };
+ * 
+ * utils.object.union(source1, source2);
+ * // [{ first: 'john', last: 'doe' },
+ * //  { first: 'jane', last: 'doe' }];
+ * ```
+ * 
+ * @param {Object[]|Object} source1 - object or array of objects to union
+ * @param {Object[]|Object} source2 - object or array of objects to union
+ * @returns {Object[]} - collection of objects merging the values between the two sources
+ * 
+ * @see {@link module:object.join|join} - to instead join based on a value instead of index
+ * @see {@link module:object.filterObjectProperties|filterObjectProperties} - to remove properties from collection of objects.
+ */
+module.exports.union = function union(source1, source2) {
+  const signature = 'union(source1:object[], source2:object[])';
+  
+  let s1Iterator;
+  let s1Entry;
+  let s1Length;
+  let s2Iterator;
+  let s2Entry;
+  let s2Length;
+  
+  if (Array.isArray(source1)) {
+    s1Iterator = source1.entries();
+    s1Length = source1.length;
+  } else if (typeof source1 === 'object') {
+    s1Iterator = ({ next: () => ({ done: false, value: [0, source1] }) });
+    s1Length = 1;
+  } else {
+    throw new Error(`${signature}: source1 must be a collection of objects, or a single object`);
+  }
+
+  if (Array.isArray(source2)) {
+    s2Iterator = source2.entries();
+    s2Length = source2.length;
+  } else if (typeof source2 === 'object') {
+    s2Iterator = ({ next: () => ({ done: false, value: [0, source2] }) });
+    s2Length = 1;
+  } else {
+    throw new Error(`${signature}: source2 must be a collection of objects, or a single object`);
+  }
+
+  const len = Math.max(s1Length, s2Length);
+  const results = new Array(len);
+
+  for (let i = 0; i < len; i += 1) {
+    s1Entry = s1Iterator.next();
+    s1Entry = s1Entry.done ? {} : s1Entry.value[1];
+
+    s2Entry = s2Iterator.next();
+    s2Entry = s2Entry.done ? {} : s2Entry.value[1];
+
+    //console.log(`s1Entry: ${JSON.stringify(s1Entry)}, s2Entry: ${JSON.stringify(s2Entry)}`);
+    results[i] = { ...s1Entry, ...s2Entry };
+  }
+
+  return results;
+};

package/src/random.js

@@ -17,6 +17,8 @@ const SimplexModule = require('./random_simplex');
  * * Simplex Noise
  *     * {@link module:random.simplexGenerator|simplexGenerator(seed)} - Number generator between -1 and 1 given an x/y/z coordinate
  * 
+ * If leveraging 
+ * 
  * While generating a simple number between two values is common, it is very important - and useful in generating fake data.
  * 
  * ```
@@ -39,6 +41,60 @@ const SimplexModule = require('./random_simplex');
  * 
  * The possibilities are endless.
  * 
+ * <hr />
+ * 
+ * <b>This library is meant to provide simple use cases.</b>
+ * Please use Standard libraries
+ * - like [d3-random](https://observablehq.com/@d3/d3-random) for additional alternatives
+ * 
+ * see {@link module:format.mapArrayDomain|format.mapArrayDomain} - as it projects a value
+ * from between a range a value, and picks the corresponding value from an array.
+ * 
+ * For example:
+ * 
+ * ```
+ * require('esm-hook');
+ * d3 = require('d3');
+ * 
+ * //-- create a number generator using Normal / Gaussian distribution
+ * randomGenerator = d3.randomNormal(
+ *  0.5, // mu - or centerline
+ *  0.1 // sigma - or spread of values
+ * );
+ * 
+ * randomValue = randomGenerator();
+ * // randomValue - 0.4
+ * 
+ * randomDataset = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'];
+ * 
+ * //-- create an array of 3 items, each with the results from randomGenerator
+ * results = utils.array.size(3, () => randomGenerator());
+ * // [ 0.6235937672428706, 0.4991359903898883, 0.4279365561645624 ]
+ * 
+ * //-- map those values to the randomDataset
+ * results.map(val => ({ pick: utils.format.mapArrayDomain(val, randomDataset) }));
+ * // [ { pick: 'g' }, { pick: 'e' }, { pick: 'e' } ]
+ * 
+ * //-- group them by the pick field
+ * //-- then add a new property called count - using the # of records with the same value
+ * groupedResults = utils.group.by(resultPicks, 'pick')
+ *     .reduce((list) => ({ count: list.length }));
+ * // [ { pick: 'g', count: 1 }, { pick: 'e', count: 2 } ]
+ * 
+ * //-- make a bar chart (only with 10k results)
+ * utils.vega.embed((vl) => {
+ *     return vl
+ *       .markBar()
+ *       .title('Distribution')
+ *       .data(groupedResults)
+ *       .encode(
+ *         vl.x().fieldN('value'),
+ *         vl.y().fieldQ('count').scale({type: 'log'})
+ *       );
+ * });
+ * ```
+ * ![Screenshot of the chart above](img/randomMap_normalDistribution.png)
+ * 
  * @module random
  */
 const RandomUtil = module.exports;
@@ -65,13 +121,14 @@ module.exports.getSeed = function getSeed() {
 };
 
 /**
- * Generate a random integer 
+ * Generate a random integer (with uniform distribution)
  * @param {Number} [min = 0] - Minimum integer (inclusive) that could be generated
  * @param {Number} [max = 100] - Maximum integer (inclusive) number that could be generated
  * @returns {Number} - number between (and including) min and max
  * @example
  * utils.random.randomInteger(0, 100) // 40
  * utils.random.randomInteger(0, 100) // 96
+ * @see [d3-random](https://observablehq.com/@d3/d3-random) for additional alternatives
  */
 module.exports.randomInteger = function randomInteger(min = 0, max = 100) {
   //-- can only occur if the user exports to htmlScript
@@ -84,11 +141,12 @@ module.exports.randomInteger = function randomInteger(min = 0, max = 100) {
 };
 
 /**
- * Generates a random floating point number
+ * Generates a random floating point number (with uniform distribution)
  * @param {Number} [min = 0] - Minimum float (inclusive) that could be generated
  * @param {Number} [max = 100] - Maximum float (inclusive) number that the value will be less than
  * @returns {Number} - number between (and including) min and max
  * utils.random.randomInteger(0, 1) // 0.224223
+ * @see [d3-random](https://observablehq.com/@d3/d3-random) for additional alternatives
  */
 module.exports.random = function random(min = 0, max = 1) {
   //-- can only occur if the user exports to htmlScript
@@ -102,11 +160,12 @@ module.exports.random = function random(min = 0, max = 1) {
 };
 
 /**
- * Picks a random value from an array of values
+ * Picks a random value from an array of values (with uniform distribution)
  * @param {Array} targetArray - Array of values to pick from
  * @returns {any} - one of the values picked at random from the target array
  * @example
  * utils.random.pickRandom(['apple', 'orange', 'pear']); // 'pear'
+ * @see [d3-random](https://observablehq.com/@d3/d3-random) for additional alternatives
  */
 module.exports.pickRandom = function pickRandom(targetArray) {
   if (!targetArray || !Array.isArray(targetArray)) {