jupyter-ijavascript-utils 1.33.0 → 1.35.0

package/DOCS.md

@@ -75,6 +75,8 @@ 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

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,8 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.33.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/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

@@ -31,6 +31,8 @@ const FormatUtils = require('./format');
  *   * {@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
@@ -536,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

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)) {