jupyter-ijavascript-utils 1.9.2 → 1.10.0

package/DOCS.md

@@ -28,6 +28,7 @@ See the [#Installation section for requirements and installation](#install)
 
 ## What's New
 
+* 1.10 - provide {@link module:aggregate.percentile|percentile} (like 50th percentile) aggregates
 * 1.9 - allow {@link TableGenerator#transpose|transposing results} on TableGenerator.
 * 1.8 - add in What can I Do tutorial, and {@link module:object.join|object.join methods}
 * 1.7 - revamp of `animation` method for ijs.htmlScript

package/README.md

@@ -7,7 +7,7 @@
     </a>
     <img src="https://img.shields.io/badge/Coverage-98-green" />
     <a href="https://github.com/paulroth3d/jupyter-ijavascript-utils" alt="npm">
-        <img src="https://img.shields.io/badge/npm-%5E1.9.2-red" />
+        <img src="https://img.shields.io/badge/npm-%5E1.10.0-red" />
     </a>
 </p>
 
@@ -21,6 +21,7 @@ See documentation at: [https://jupyter-ijavascript-utils.onrender.com/](https://
 
 # What's New
 
+* 1.10 - provide percentile (like 50th percentile) aggregates
 * 1.9 - allow transposing results on TableGenerator.
 * 1.8 - add in What can I Do tutorial, and object.join methods
 * 1.7 - revamp of `animation` method to htmlScript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",
@@ -27,7 +27,6 @@
     "jupyter"
   ],
   "author": "Paul Roth",
-  "license": "MIT",
   "devDependencies": {
     "babel-eslint": "^10.1.0",
     "docdash": "^1.2.0",
@@ -44,6 +43,7 @@
     "fs-extra": "^10.0.1",
     "generate-schema": "^2.6.0",
     "node-fetch": "^2.6.5",
+    "percentile": "^1.6.0",
     "pino": "^6.12.0",
     "pino-pretty": "^5.1.2",
     "plantuml-encoder": "^1.4.0",

package/src/TableGenerator.js

@@ -13,7 +13,7 @@
 
 const { printValue } = require('./format');
 
-const generateRange = (length, defaultValue) => new Array(length).fill(defaultValue);
+// const generateRange = (length, defaultValue) => new Array(length).fill(defaultValue);
 
 const IJSUtils = require('./ijs');
 
@@ -452,20 +452,64 @@ class TableGenerator {
    * 
    * (This is an alternate to {@link formatterFn} or simple `.map()` call on the source data)
    * 
+   * **NOTE: Only matching properties on the formatter object are changed - all others are left alone.**
+   * 
    * For example:
    * 
    * ```
-   * data = [{temp: 98, type: 'F'}, {temp: 99, type: 'F'}, {temp: 100, type: 'F'}];
+   * data = [
+   *   {station: 'A', temp: 98, type: 'F', descr: '0123'},
+   *   {station: 'A', temp: 99, type: 'F', descr: '0123456'},
+   *   {station: 'A', temp: 100, type: 'F', descr: '0123456789'}
+   * ];
    * 
    * //-- simple example where the temp property is converted, and type property overwritten
    * new TableGenerator(data)
    *  .formatter({
+   *    //-- property 'station' not mentioned, so no change
+   *    
+   *    //-- convert temperature to celsius
    *    temp: (value) => (value - 32) * 0.5556,
-   *    type: (value) => 'C'
-   *  })...
+   *    //-- overwrite type from 'F' to 'C'
+   *    type: 'C',
+   *    //-- ellipsify to shorten the description string, if longer than 8 characters
+   *    descr: (str) => utils.format.ellipsify(str, 8)
+   *  }).renderMarkdown()
    * ```
    * 
-   * Only properties on the object are checked - all others are left alone.
+   * station|temp  |type|descr    
+   * --     |--    |--  |--       
+   * A      |36.67 |F   |0123     
+   * A      |37.225|F   |0123456  
+   * A      |37.781|F   |01234567…
+   * 
+   * Note, due to frequent requests, simple datatype conversions can be requested.
+   * 
+   * Only ('String', 'Number', and 'Boolean') are supported
+   * 
+   * ```
+   * data = [
+   *   { propA: ' 8009', propB: 8009, isBoolean: 0},
+   *   { propA: ' 92032', propB: 92032, isBoolean: 1},
+   *   { propA: ' 234234', propB: 234234, isBoolean: 1},
+   * ];
+   * 
+   * new utils.TableGenerator(data)
+   *   .formatter({
+   *     //-- convert Prop A to Number - so render with Locale Number Formatting
+   *     propA: 'number',
+   *     //-- conver PropB to String - so render without Locale Number Formatting
+   *     propB: 'string',
+   *     //-- render 'True' or 'False'
+   *     isBoolean: 'boolean'
+   *   }).renderMarkdown();
+   * ```
+   * 
+   * propA|propB|isBoolean
+   * --                  |--                |--       
+   * 8,009               |8009              |false    
+   * 92,032              |92032             |true     
+   * 234,234             |234234            |true 
    * 
    * @param {Object} obj - object with properties storing arrow functions
    * @param {Function} obj.PropertyToTranslate - (value) => result
@@ -480,10 +524,25 @@ class TableGenerator {
 
     const fnMap = new Map();
     Object.getOwnPropertyNames(obj).forEach((key) => {
-      if ((typeof obj[key]) !== 'function') {
-        throw (Error(`Formatter properties must be functions. [${key}]`));
+      if ((typeof obj[key]) === 'string') {
+        let fn;
+        const str = obj[key].toLowerCase();
+        if (str === 'string') {
+          fn = (val) => String(val);
+        } else if (str === 'number') {
+          fn = (val) => Number(val);
+        } else if (str === 'boolean') {
+          fn = (val) => val ? 'true' : 'false';
+        } else {
+          throw Error(`TableGenerator.format: property ${key} formatter of ${str} is unsupported. Only (String, Number, Boolean) are supported`);
+        }
+        fnMap.set(key, fn);
+      } else {
+        if ((typeof obj[key]) !== 'function') {
+          throw (Error(`Formatter properties must be functions. [${key}]`));
+        }
+        fnMap.set(key, obj[key]);
       }
-      fnMap.set(key, obj[key]);
     });
     
     this.#formatterFn = ({ value, property }) => fnMap.has(property)

package/src/aggregate.js

@@ -1,5 +1,7 @@
 /* eslint-disable implicit-arrow-linebreak */
 
+const Percentile = require('percentile');
+
 const ObjectUtils = require('./object');
 const FormatUtils = require('./format');
 
@@ -13,6 +15,8 @@ const FormatUtils = require('./format');
  * 
  * Types of methods:
  * 
+ * * Select a single property
+ *   * {@link module:aggregate.property|property()} - maps to a single property (often used with other libraries)
  * * Ranges of values
  *   * {@link module:aggregate.extent|extent()} - returns the min and max of range
  *   * {@link module:aggregate.min|min()} - returns the minimum value of the range
@@ -35,6 +39,17 @@ const FormatUtils = require('./format');
  *   * {@link module:aggregate.sum|sum()} - sum of a collection
  * * Functional
  *   * {@link module:aggregate.deferCollection|deferCollection(function, bindArg, bindArg, ...)} - bind a function with arguments
+ * * Percentile
+ *   * {@link module:aggregate.percentile|percentile()} - determines the Nth percentile of a field or value
+ *   * {@link module:aggregate.percentile_01|percentile_01()} - 1th percentile
+ *   * {@link module:aggregate.percentile_05|percentile_05()} - 5th percentile
+ *   * {@link module:aggregate.percentile_10|percentile_10()} - 10th percentile
+ *   * {@link module:aggregate.percentile_25|percentile_25()} - 25th percentile
+ *   * {@link module:aggregate.percentile_50|percentile_50()} - 50th percentile
+ *   * {@link module:aggregate.percentile_75|percentile_75()} - 75th percentile
+ *   * {@link module:aggregate.percentile_90|percentile_90()} - 90th percentile
+ *   * {@link module:aggregate.percentile_95|percentile_95()} - 95th percentile
+ *   * {@link module:aggregate.percentile_99|percentile_99()} - 99th percentile
  * 
  * Please note, there is nothing special for these functions, such as working with {@link SourceMap#reduce|SourceMap.reduce()}
  * 
@@ -225,6 +240,34 @@ module.exports = {};
 // eslint-disable-next-line no-unused-vars
 const AggregateUtils = module.exports;
 
+/**
+ * Maps an array of values to a single property.
+ * 
+ * For example:
+ * 
+ * ```
+ * const data = [{ record: 'jobA', val: 1 }, { record: 'jobA', val: 2 },
+ *  { record: 'jobA', val: 3 }, { record: 'jobA', val: 4 },
+ *  { record: 'jobA', val: 5 }, { record: 'jobA', val: 6 },
+ *  { record: 'jobA', val: 7 }, { record: 'jobA', val: 8 },
+ *  { record: 'jobA', val: 9 }, { record: 'jobA', val: 10 }
+ * ];
+ * 
+ * utils.object.propertyFromList(data, 'val')
+ * //-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * 
+ * utils.object.propertyFromList(data, (r) => r.val);
+ * //-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * ```
+ * 
+ * @param {Object[]} objectArray - Array of Objects to be mapped to a single property / value
+ * @param {Function | String} propertyOrFn - Name of the property or Function to return a value
+ * @returns {Array} - Array of values
+ */
+module.exports.property = function propertyFromList(objectArray, propertyOrFn) {
+  return ObjectUtils.propertyFromList(objectArray, propertyOrFn);
+};
+
 /**
  * Converts an aggregate function to two functions -
  * one that takes all arguments except the collection
@@ -662,3 +705,157 @@ module.exports.isUnique = function isUnique(collection, accessor) {
   });
   return duplicateValue === undefined;
 };
+
+/**
+ * Returns a given percentile from a list of objects.
+ * 
+ * **Note: this simply aggregates the values and passes to the [Percentile NPM Package](https://www.npmjs.com/package/percentile)**
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @param {Number} pct - Percentile (either .5 or 50)
+ * @returns {Number} - the pct percentile of a property within the collection
+ * @example
+ * const data = [{ record: 'jobA', val: 1 }, { record: 'jobA', val: 2 },
+ *  { record: 'jobA', val: 3 }, { record: 'jobA', val: 4 },
+ *  { record: 'jobA', val: 5 }, { record: 'jobA', val: 6 },
+ *  { record: 'jobA', val: 7 }, { record: 'jobA', val: 8 },
+ *  { record: 'jobA', val: 9 }, { record: 'jobA', val: 10 }
+ * ];
+ * 
+ * utils.aggregate.percentile(data, 'val', 50) //-- returns 5
+ * utils.aggregate.percentile(data, (r) => r.val, 70) //-- returns 7
+ */
+module.exports.percentile = function percentile(collection, accessor, pct) {
+  const values = ObjectUtils.propertyFromList(collection, accessor);
+  const cleanPercentile = pct > 0 && pct < 1
+    ? pct * 100
+    : pct;
+  return Percentile(cleanPercentile, values);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_01 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 1);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_05 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 5);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_10 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 10);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_25 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 25);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_50 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 50);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_75 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 75);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_90 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 90);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_95 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 95);
+};
+
+/**
+ * Returns a hard coded percentage
+ * 
+ * {@link module:aggregate.percentage|See Percentage for more detail}
+ * 
+ * @param {Object[]} collection - collection of objects
+ * @param {Function | String} accessor - function to access the value, string property or null
+ * @returns {Number} - the percentile of a property within the collection
+ * @see {@link module:aggregate.percentile|percentile} - as this simply hard codes the percentage
+ */
+module.exports.percentile_99 = function percentile(collection, accessor) {
+  return AggregateUtils.percentile(collection, accessor, 99);
+};

package/src/format.js

@@ -12,6 +12,7 @@
  * * Formatting Strings
  *   * {@link module:format.capitalize|format.capitalize} - Capitalizes only the first character in the string (ex: 'John paul');
  *   * {@link module:format.capitalizeAll|format.capitalizeAll} - Capitalizes all the words in a string (ex: 'John Paul')
+ *   * {@link module:format.ellipsify|format.ellipsify} - Truncates a string if the length is 'too long'
  * * Formatting Time
  *   * {@link module:format.millisecondDuration|format.millisecondDuration}
  * * Mapping Values

package/src/object.js

@@ -22,6 +22,7 @@ const schemaGenerator = require('generate-schema');
  *   * {@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
  * * Rename properties
  *   * {@link module:object.cleanProperties|cleanProperties()} - correct inaccessible property names in a list of objects
  *   * {@link module:object.cleanPropertyNames|cleanPropertyNames()} - create a translation of inaccessible names to accessible ones
@@ -638,6 +639,40 @@ module.exports.joinProperties = function join(objectArray, indexField, targetMap
   return ObjectUtils.join(objectArray, indexField, targetMap, joinFn);
 };
 
+/**
+ * Maps an array of values to a single property.
+ * 
+ * For example:
+ * 
+ * ```
+ * const data = [{ record: 'jobA', val: 1 }, { record: 'jobA', val: 2 },
+ *  { record: 'jobA', val: 3 }, { record: 'jobA', val: 4 },
+ *  { record: 'jobA', val: 5 }, { record: 'jobA', val: 6 },
+ *  { record: 'jobA', val: 7 }, { record: 'jobA', val: 8 },
+ *  { record: 'jobA', val: 9 }, { record: 'jobA', val: 10 }
+ * ];
+ * 
+ * utils.object.propertyFromList(data, 'val')
+ * //-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * 
+ * utils.object.propertyFromList(data, (r) => r.val);
+ * //-- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * ```
+ * 
+ * @param {Object[]} objectArray - Array of Objects to be mapped to a single property / value
+ * @param {Function | String} propertyOrFn - Name of the property or Function to return a value
+ * @returns {Array} - Array of values
+ */
+module.exports.propertyFromList = function propertyFromList(objectArray, propertyOrFn) {
+  const cleanArray = Array.isArray(objectArray)
+    ? objectArray
+    : [];
+  
+  const fn = ObjectUtils.evaluateFunctionOrProperty(propertyOrFn);
+
+  return cleanArray.map(fn);
+};
+
 /**
  * Finds objects that do not have ALL the properties specified.
  *