jupyter-ijavascript-utils 1.30.0 → 1.31.0

package/DOCS.md

@@ -75,6 +75,7 @@ Give it a try here:
 
 ## What's New
 
+* 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.31.0

package/README.md

@@ -55,6 +55,7 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 # What's New
 
+* 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.31.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

@@ -26,6 +26,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 +302,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 +367,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;
 
@@ -466,5 +504,3 @@ module.exports.arrangeMulti = function arangeMulti(...dimensions) {
   return ArrayUtils.size(currentDimension, () => ArrayUtils.clone(childDimensionalValue));
 };
 module.exports.arangeMulti = module.exports.arrangeMulti;
-
-//-- collection utilities