jupyter-ijavascript-utils 1.30.0 → 1.32.0

package/DOCS.md

@@ -75,6 +75,8 @@ Give it a try here:
 
 ## What's New
 
+* 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
 * 1.29 - Updated TableGenerator.format method
 * 1.28 - Sticky table headers for table.render

package/Dockerfile

@@ -1,3 +1,3 @@
 # syntax=docker/dockerfile:1
 
-FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.30.0
+FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.32.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.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
 * 1.29 - Updated TableGenerator.format method
 * 1.28 - Sticky table headers for table.render

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.30.0",
+  "version": "1.32.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",
@@ -40,7 +40,7 @@
     "eslint-plugin-import": "^2.26.0",
     "eslint-watch": "^7.0.0",
     "jest": "^27.0.6",
-    "jsdoc": "^3.6.10",
+    "jsdoc": "^4.0.2",
     "sinon": "^11.1.1"
   },
   "dependencies": {

package/src/TableGenerator.js

@@ -135,10 +135,14 @@ const { createSort } = require('./array');
  *   * {@link TableGenerator#generateHTML|generateHTML()} - returns html table with the results
  *   * {@link TableGenerator#generateMarkdown|generateMarkdown()} - returns markdown with the results
  *   * {@link TableGenerator#generateCSV|generateCSV()} - generates a CSV with the results
+ *   * {@link TableGenerator#generateCSV|generateCSV()} - generates a TSV with the results
  *   * {@link TableGenerator#generateArray|generateArray()} - generates an array of headers and data for further process
  *   * {@link TableGenerator#generateArray2|generateArray2()} - generates a single array for further process
  * * render in jupyter
  *   * {@link TableGenerator#render|render()} - renders the results in a table within jupyter
+ *   * {@link TableGenerator#renderCSV|renderCSV()} - renders the generateCSV results in a table within jupyter
+ *   * {@link TableGenerator#renderTSV|renderTSV()} - renders the generateTSV results in a table within jupyter
+ *   * {@link TableGenerator#renderMarkdown|renderMarkdown()} - renders the generateMarkdown results in a table within jupyter
  * 
  */
 class TableGenerator {
@@ -1398,6 +1402,43 @@ class TableGenerator {
     return tableResults;
   }
 
+  /**
+   * Generates a TSV Table
+   * @see {@link TableGenerator#renderCSV}
+   */
+  generateTSV() {
+    const results = this.prepare();
+
+    const printOptions = this.#printOptions;
+    
+    const escapeString = (val) => {
+      //-- always return as string values to preserve formatting
+      return `"${
+        printValue(val, printOptions)
+          .replace(/"/g, '""')
+      }"`;
+    };
+    const tsvify = (a) => a.map(escapeString)
+      .join('\t');
+
+    const printHeader = (headers, style) => tsvify(headers)
+      + '\n';
+
+    const printBody = (collection) => collection
+      .map((dataRow) => tsvify(dataRow))
+      .join('\n');
+    
+    // const cleanFn = printValue;
+    // .map((dataRow) => tsvify(dataRow.map((value) =>
+    //   cleanFn(value, printOptions))
+    // )).join('\n');
+    
+    const tableResults = printHeader(results.headers, '')
+      + printBody(results.data);
+
+    return tableResults;
+  }
+
   /**
    * @typedef {Object} TableArray
    * @property {String} headers -
@@ -1601,6 +1642,44 @@ class TableGenerator {
 
     context.console.log(this.generateCSV());
   }
+
+  /**
+   * Renders Markdown in the cell results
+   * @see {@link TableGenerator#generateTSV}
+   * @example
+   * weather = [
+   *   { id: 1, city: 'Seattle',  month: 'Aug', precip: 0.87 },
+   *   { id: 0, city: 'Seattle',  month: 'Apr', precip: 2.68 },
+   *   { id: 2, city: 'Seattle',  month: 'Dec', precip: 5.31 },
+   *   { id: 3, city: 'New York', month: 'Apr', precip: 3.94 },
+   *   { id: 4, city: 'New York', month: 'Aug', precip: 4.13 },
+   *   { id: 5, city: 'New York', month: 'Dec', precip: 3.58 },
+   *   { id: 6, city: 'Chicago',  month: 'Apr', precip: 3.62 },
+   *   { id: 8, city: 'Chicago',  month: 'Dec', precip: 2.56 },
+   *   { id: 7, city: 'Chicago',  month: 'Aug', precip: 3.98 }
+   * ];
+   * utils.table(weather)
+   *     .renderTSV();
+   * 
+   * // "id","city","month","precip"
+   * // "1","Seattle","Aug","0.87"
+   * // "0","Seattle","Apr","2.68"
+   * // "2","Seattle","Dec","5.31"
+   * // "3","New York","Apr","3.94"
+   * // "4","New York","Aug","4.13"
+   * // "5","New York","Dec","3.58"
+   * // "6","Chicago","Apr","3.62"
+   * // "8","Chicago","Dec","2.56"
+   * // "7","Chicago","Aug","3.98"
+   */
+  renderTSV() {
+    const context = IJSUtils.detectContext();
+    if (!context) {
+      throw (Error('Not in iJavaScript, no $$ variable available'));
+    }
+
+    context.console.log(this.generateTSV());
+  }
 }
 
 module.exports = TableGenerator;

package/src/array.js

@@ -17,6 +17,7 @@ require('./_types/global');
  *   * {@link module:array.createSort|array.createSort(sortIndex, sortIndex, ...)} - generates a sorting function
  *   * {@link module:array.SORT_ASCENDING|array.SORT_ASCENDING} - common ascending sorting function for array.sort()
  *   * {@link module:array.SORT_DESCENDING|array.SORT_DESCENDING} - common descending sorting function for array.sort()
+ *   * {@link module:array.indexify|array.indexify} - identify sections within a 1d array to create a hierarchy.
  * * Rearrange Array
  *   * {@link module:array.reshape|array.reshape} - reshapes an array to a size of rows and columns
  *   * {@link module:array.transpose|array.transpose} - transposes (flips - the array along the diagonal)
@@ -26,6 +27,8 @@ require('./_types/global');
  *   * {@link module:array.pickRows|array.pickRows} - picks a row from a 2d array
  *   * {@link module:array.pickColumns|array.pickColumns} - picks a column from a 2d array
  *   * {@link module:array.pick|array.pick} - picks either/or rows and columns
+ * * Understanding Values
+ *   * {@link module:array.isMultiDimensional|array.isMultiDimensional} - determines if an array is multi-dimensional
  * 
  * @module array
  * @exports array
@@ -300,6 +303,42 @@ module.exports.arrange = function arange(len, start = 0, step = 1) {
  */
 module.exports.arange = module.exports.arrange;
 
+/**
+ * Determine whether an array is multi-dimensional (an array of arrays)
+ * 
+ * For example:
+ * 
+ * ```
+ * utils.array.isMultiDimensional(0); // false
+ * utils.array.isMultiDimensional([0,1,2,3]); // false
+ * utils.array.isMultiDimensional([[0,1], [2,3]]); // true
+ * utils.array.isMultiDimensional([0, [1,2]]); // true
+ * ```
+ * 
+ * @param {Array} targetArray - array to check if multi-dimensional
+ * @returns {Boolean} - if the targetArray has any values that are multi-dimensional
+ */
+module.exports.isMultiDimensional = function isMultiDimensional(targetArray) {
+  if (!targetArray || !Array.isArray(targetArray)) {
+    return false;
+  }
+  return targetArray.find((v) => Array.isArray(v)) !== undefined;
+};
+
+/**
+ * Determines the depth of a two dimensional array
+ * @param {Array} targetArray - two dimensional array
+ * @returns {Number}
+ * @private
+ */
+module.exports.arrayLength2d = function arrayLength2d(targetArray) {
+  return (targetArray || [])
+    .reduce((max, line) => {
+      const len = (line || []).length;
+      return (len > max) ? len : max;
+    }, 0);
+};
+
 /**
  * Transposes a two dimensional array, so an NxM becomes MxN
  * @param {any[]} matrix - MxN array
@@ -329,7 +368,7 @@ module.exports.transpose = function transpose(matrix) {
 
   //-- for speed, we use for loops.
   const rows = matrix.length;
-  const cols = matrix[0].length;
+  const cols = ArrayUtils.arrayLength2d(matrix); // matrix[0].length; 
   let colI;
   let rowI;
 
@@ -467,4 +506,180 @@ module.exports.arrangeMulti = function arangeMulti(...dimensions) {
 };
 module.exports.arangeMulti = module.exports.arrangeMulti;
 
-//-- collection utilities
+/** 
+ * Create a unique number index for each element in an array,
+ * alternatively using additional functions to indicate hierarchies of data.
+ * 
+ * For example, markdown can be considered a hierarchy of data:
+ * 
+ * ```
+ * markdownList = `# Overview
+ * This entire list is a hierarchy of data.
+ * 
+ * # Section A
+ * This describes section A
+ * 
+ * ## SubSection 1
+ * With a subsection belonging to Section A
+ * 
+ * ## SubSection 2
+ * And another subsection sibling to SubSection 1, but also under Section A.
+ * 
+ * # Section B
+ * With an entirely unrelated section B, that is sibling to Section A
+ * 
+ * ## SubSection 1
+ * And another subsection 1, but this time related to Section B.`;
+ * ```
+ * 
+ * And we want to convert this 1d array into a hierarchy.
+ * 
+ * ```
+ * data = markdownList.split('\n')
+ *    .filter(line => line ? true : false); // check for empty lines
+ * 
+ * utils.format.consoleLines( data, 4);
+ * // ['# Overview',
+ * // 'This entire list is a hierarchy of data.',
+ * // '# Section A',
+ * // 'This describes section A',;
+ * 
+ * //-- functions that return True if we are in a new "group"
+ * isHeader1 = (str) => str.startsWith('# ');
+ * 
+ * isHeader1('# Overview'); // true
+ * isHeader1('This entire list is a hierarchy of data'); // false
+ * isHeader1('# Section A'); // true
+ * isHeader1('This describes section A'); // false
+ * 
+ * indexedData = utils.array.indexify(data, isHeader1);
+ * [
+ *   { entry: 'Heading', section: [ 0 ], subIndex: 1 },
+ *   { entry: '# Overview', section: [ 1 ], subIndex: 0 },
+ *   {
+ *     entry: 'This entire list is a hierarchy of data.',
+ *     section: [ 1 ],
+ *     subIndex: 1
+ *   },
+ *   { entry: '# Section A', section: [ 2 ], subIndex: 0 },
+ *   { entry: 'This describes section A', section: [ 2 ], subIndex: 1 },
+ *   { entry: '## SubSection 1', section: [ 2 ], subIndex: 2 },
+ *   {
+ *     entry: 'With a subsection belonging to Section A',
+ *     section: [ 2 ],
+ *     subIndex: 3
+ *   },
+ *   { entry: '## SubSection 2', section: [ 2 ], subIndex: 4 },
+ *   {
+ *     entry: 'And another subsection sibling to SubSection 1, but also under Section A.',
+ *     section: [ 2 ],
+ *     subIndex: 5
+ *   },
+ *   { entry: '# Section B', section: [ 3 ], subIndex: 0 },
+ *   {
+ *     entry: 'With an entirely unrelated section B, that is sibling to Section A',
+ *     section: [ 3 ],
+ *     subIndex: 1
+ *   },
+ *   { entry: '## SubSection 1', section: [ 3 ], subIndex: 2 },
+ *   {
+ *     entry: 'And another subsection 1, but this time related to Section B.',
+ *     section: [ 3 ],
+ *     subIndex: 3
+ *   }
+ * ];
+ * ```
+ * 
+ * Note that this only indexes elements by the first header.
+ * 
+ * To index this with two levels of hierarchy, we can pass another function.
+ * 
+ * ```
+ * isHeader2 = (str) => str.startsWith('## ');
+ * 
+ * isHeader2('# Overview'); // false
+ * isHeader2('This entire list is a hierarchy of data'); // false
+ * isHeader2('# Section A'); // true
+ * isHeader2('This describes section A'); // false
+ * 
+ * indexedData = utils.array.indexify(data, isHeader1, isHeader2);
+ * // [
+ * //   { entry: 'Heading', section: [ 0, 0 ], subIndex: 1 },
+ * //   { entry: '# Overview', section: [ 1, 0 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'This entire list is a hierarchy of data.',
+ * //     section: [ 1, 0 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '# Section A', section: [ 2, 0 ], subIndex: 0 },
+ * //   { entry: 'This describes section A', section: [ 2, 0 ], subIndex: 1 },
+ * //   { entry: '## SubSection 1', section: [ 2, 1 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'With a subsection belonging to Section A',
+ * //     section: [ 2, 1 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '## SubSection 2', section: [ 2, 2 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'And another subsection sibling to SubSection 1, but also under Section A.',
+ * //     section: [ 2, 2 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '# Section B', section: [ 3, 0 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'With an entirely unrelated section B, that is sibling to Section A',
+ * //     section: [ 3, 0 ],
+ * //     subIndex: 1
+ * //   },
+ * //   { entry: '## SubSection 1', section: [ 3, 1 ], subIndex: 0 },
+ * //   {
+ * //     entry: 'And another subsection 1, but this time related to Section B.',
+ * //     section: [ 3, 1 ],
+ * //     subIndex: 1
+ * //   }
+ * // ];
+ * ```
+ */
+module.exports.indexify = function indexify(source, ...sectionIndicatorFunctions) {
+  const functionSignature = 'indexify(source, ...sectionIndicatorFunctions)';
+
+  const counters = new Array(sectionIndicatorFunctions.length).fill(0);
+  let subIndex = 0;
+  // counters[counters.length - 1] = -1;
+
+  //-- validate inputs
+  if (!Array.isArray(source)) {
+    throw new Error(`${functionSignature}: source must be an array`);
+  }
+  sectionIndicatorFunctions.forEach((fn) => {
+    if (typeof fn !== 'function') {
+      throw new Error(`${functionSignature}: all section indicators passed must be functions`);
+    }
+  });
+
+  const results = source.map((entry) => {
+    let isNewSectionTripped = false;
+
+    sectionIndicatorFunctions.forEach((fn, index) => {
+      if (isNewSectionTripped) {
+        counters[index] = 0;
+      } else {
+        isNewSectionTripped = fn(entry) ? true : false;
+
+        if (isNewSectionTripped) {
+          counters[index] += 1;
+        }
+      }
+    });
+
+    if (isNewSectionTripped) {
+      subIndex = 0;
+    } else {
+      subIndex += 1;
+    }
+
+    return ({ entry, section: [...counters], subIndex });
+  });
+
+  return results;
+};