jupyter-ijavascript-utils 1.8.3 → 1.9.1

package/DOCS.md

@@ -28,7 +28,8 @@ See the [#Installation section for requirements and installation](#install)
 
 ## What's New
 
-* 1.8 - add in What can I Do tutorial, and object.join methods
+* 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
 * 1.6 - add SVG support for rendering SVGs and animations with {@link module:svg}.
 * 1.5 - Add LaTeX / KaTeX support with {@link module:latex} for rendering Math formulas and PlantUML support for Diagrams

package/README.md

@@ -6,6 +6,9 @@
         <img src="https://img.shields.io/badge/License-MIT-green" />
     </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.1-red" />
+    </a>
 </p>
 
 # Overview
@@ -18,6 +21,7 @@ See documentation at: [https://jupyter-ijavascript-utils.onrender.com/](https://
 
 # What's New
 
+* 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
 * 1.6 - add SVG support for rendering SVGs and animations

package/package.json

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

package/src/TableGenerator.js

@@ -17,6 +17,8 @@ const generateRange = (length, defaultValue) => new Array(length).fill(defaultVa
 
 const IJSUtils = require('./ijs');
 
+const ArrayUtils = require('./array');
+
 const { createSort } = require('./array');
 
 /**
@@ -62,29 +64,32 @@ const { createSort } = require('./array');
  * * change the columns and headers
  *   * {@link TableGenerator#columns|columns(field, field, ...)} - specify fields and order
  *   * {@link TableGenerator#columnsToExclude|columnsToExclude(field, ...)} - specify fields not to show
- *   * {@link TableGenerator#labels|lables(obj} - labels for field headers
+ *   * {@link TableGenerator#labels|lables(obj)} - labels for field headers
  * * augment and change the values (non-destructively)
- *   * {@link TableGenerator#formatter|formatter(obj} - adjust values of specific fields
- *   * {@link TableGenerator#formatterFn|formatterFn(fn} - row, column aware adjustment
- *   * {@link TableGenerator#printOptions|printOptions(object} - options for value rendering
+ *   * {@link TableGenerator#formatter|formatter(obj)} - adjust values of specific fields
+ *   * {@link TableGenerator#formatterFn|formatterFn(fn)} - row, column aware adjustment
+ *   * {@link TableGenerator#printOptions|printOptions(object)} - options for value rendering
  *   * {@link TableGenerator#augment|augment(obj)} - add fields to table
  * * sort and limit the output
- *   * {@link TableGenerator#filter|filter(fn))} - determine which rows to include or not
- *   * {@link TableGenerator#limit|limit(number} - limit only specific # of rows
- *   * {@link TableGenerator#sortFn|sortFn(fn} - Standard Array sort function
- *   * {@link TableGenerator#sort|sort(field, field, ...} - sorts by fields, or descending with -
+ *   * {@link TableGenerator#filter|filter(fn)} - determine which rows to include or not
+ *   * {@link TableGenerator#limit|limit(number)} - limit only specific # of rows
+ *   * {@link TableGenerator#sortFn|sortFn(fn)} - Standard Array sort function
+ *   * {@link TableGenerator#sort|sort(field, field, ...)} - sorts by fields, or descending with '-'
+ * * transpose the output
+ *   * {@link TableGenerator#transpose|transpose()} - transposes the output prior to rendering
  * * style the table
- *   * {@link TableGenerator#styleTable|styleTable(string} - css style for the table
- *   * {@link TableGenerator#styleHeader|styleHeader(string} - css styles for the header row
+ *   * {@link TableGenerator#styleTable|styleTable(string)} - css style for the table
+ *   * {@link TableGenerator#styleHeader|styleHeader(string)} - css styles for the header row
  *   * {@link TableGenerator#styleRow|styleRow(fn)} - Function to style rows
- *   * {@link TableGenerator#styleCell|styleCell(fn} - Function to style cells
+ *   * {@link TableGenerator#styleCell|styleCell(fn)} - Function to style cells
  * * generate output
- *   * {@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#generateArray|generateArray(} - generates an array for further process
+ *   * {@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#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#render|render()} - renders the results in a table within jupyter
  * 
  */
 class TableGenerator {
@@ -191,6 +196,12 @@ class TableGenerator {
    */
   #styleCell = null;
 
+  /**
+   * Whether the data should be output transposed
+   * @type {Boolean}
+   */
+  #isTransposed = false;
+
   /**
    * Function to format a value for a cell
    * 
@@ -237,6 +248,7 @@ class TableGenerator {
     this.#styleHeader = '';
     this.#styleRow = null;
     this.#styleCell = null;
+    this.#isTransposed = false;
   }
 
   //--    GETTER SETTERS
@@ -781,6 +793,53 @@ class TableGenerator {
     return this;
   }
 
+  /**
+   * Transposes (flips along the diagonal) prior to output.
+   * 
+   * This can be very handy for wide, but short, tables.
+   * 
+   * For example, given the data:
+   * 
+   * ```
+   * const data = [
+   *   { name: 'John', color: 'green', age: 23, hair: 'blond', state: 'IL' },
+   *   { name: 'Jane', color: 'brown', age: 23, hair: 'blonde', state: 'IL' }
+   * ];
+   * ```
+   * 
+   * Running normally would give
+   * 
+   * ```
+   * new utils.TableGenerator(data)
+   *    .generateMarkdown();
+   * ```
+   * 
+   * name|color|age|hair  |state
+   * --  |--   |-- |--    |--
+   * John|green|23 |blond |IL
+   * Jane|brown|23 |blonde|IL
+   * 
+   * Running that transposed flips it.
+   * 
+   * ```
+   * new utils.TableGenerator(data)
+   *  .transpose()
+   *  .generateMarkdown();
+   * ```
+   * 
+   * name |John |Jane
+   * --   |--   |--
+   * color|green|brown
+   * age  |23   |23
+   * hair |blond|blonde
+   * state|IL   |IL
+   * @returns {TableGenerator}
+   */
+  transpose() {
+    this.#isTransposed = true;
+    return this;
+  }
+
   //-- Table Generation
 
   /**
@@ -833,7 +892,7 @@ class TableGenerator {
           record: row
         }));
 
-    const headers = keys.map(translateHeader);
+    let headers = keys.map(translateHeader);
     let data = cleanCollection.map(translateData);
 
     if (this.#limit < 0) {
@@ -842,6 +901,15 @@ class TableGenerator {
       data = data.slice(0, this.#limit);
     }
 
+    if (this.#isTransposed) {
+      let transposedResults = [headers, ...data];
+      transposedResults = ArrayUtils.transpose(transposedResults);
+
+      // eslint-disable-next-line prefer-destructuring
+      headers = transposedResults[0];
+      data = transposedResults.slice(1);
+    }
+
     return ({ headers, data });
   }
 
@@ -995,8 +1063,10 @@ class TableGenerator {
    */
 
   /**
-   * Generates an array of objects
+   * Generates an a result set to allow for further processing
    * 
+   * @see {@link TableGenerator#generateArray2|generateArray2()}
+   * @returns {TableArray}
    * @example
    * 
    * dataSet = [{reg:'z', source: 'A', temp: 99},
@@ -1019,14 +1089,44 @@ class TableGenerator {
    *     ['A', 100],
    *   ]
    * }
-   * 
-   * @returns {TableArray}
    */
-  generateArray() {
+  generateArray(returnUnifiedArray = false) {
     const results = this.prepare();
     return results;
   }
 
+  /**
+   * Generates an array of objects in a 2d Array
+   * 
+   * NOTE: this can be helpful for needing to transpose results
+   * 
+   * @returns {any[][]} - 2d array with both headers and data included
+   * @see {@link TableGenerator#generateArray|generateArray()}
+   * @example
+   * 
+   * dataSet = [{reg:'z', source: 'A', temp: 99},
+   *    {reg: 'z', source: 'B', temp: 98},
+   *    {reg: 'z', source:'A', temp: 100}
+   * ];
+   * 
+   * //-- only show the temp and source columns
+   * new TableGenerator(dataSet)
+   *  .columnsToExclude('reg') // or .columnsToExclude(['reg'])
+   *  .generateArray2();
+   * 
+   * //--
+   * [
+   *  ['source', 'temp'],
+   *  ['A', 99],
+   *  ['B', 98],
+   *  ['A', 100],
+   * ];
+   */
+  generateArray2() {
+    const results = this.prepare();
+    return [...results.headers, ...results.data];
+  }
+
   /**
    * Renders the html table in the cell results.
    * 

package/src/array.js

@@ -16,8 +16,14 @@ require('./_types/global');
  *   * {@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()
  * * Rearrange Array
- *   * {@link module:array.reshape|array.reshape}
- *   * {@link module:array.transpose|array.transpose}
+ *   * {@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)
+ * * Picking Values
+ *   * {@link module:array.peekFirst|array.peekFirst} - peeks at the first value in the list
+ *   * {@link module:array.peekLast|array.peekLast} - peeks at the last value in the list
+ *   * {@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
  * 
  * @module array
  * @exports array
@@ -101,18 +107,144 @@ module.exports.createSort = (...fields) => {
   });
 };
 
+/**
+ * Peek in an array and return the first value in the array.
+ * 
+ * Or return the default value (`defaultVal`) - if the array is empty
+ * 
+ * @param {Array} targetArray - array to be peeked within
+ * @param {any} defaultVal - the value to return if the array is empty
+ * @returns {any}
+ */
 module.exports.peekFirst = function peekFirst(targetArray, defaultVal = null) {
   return (Array.isArray(targetArray) && targetArray.length > 0)
     ? targetArray[0]
     : defaultVal;
 };
 
+/**
+ * Peek in an array and return the last value in the array.
+ * 
+ * Or return the default value (`defaultVal`) - if the array is empty
+ * 
+ * @param {Array} targetArray - array to be peeked within
+ * @param {any} defaultVal - the value to return if the array is empty
+ * @returns {any}
+ */
 module.exports.peekLast = function peekLast(targetArray, defaultVal = null) {
   return (Array.isArray(targetArray) && targetArray.length > 0)
     ? targetArray[targetArray.length - 1]
     : defaultVal;
 };
 
+/**
+ * Picks a row (or multiple rows) from a 2d array.
+ * 
+ * Please also see [Danfo.js](https://danfo.jsdata.org/) for working with DataFrames.
+ * 
+ * @param {Array} array2d - 2d array to pick from [row][column]
+ * @param {...Number} rowIndices - Indexes of the row to return, [0...length-1]
+ * @returns - Array with only those rows
+ * @example
+ * data = [
+ *  ['john', 23, 'purple'],
+ *  ['jane', 32, 'red'],
+ *  ['ringo', 27, 'green']
+ * ];
+ * 
+ * utils.array.pickRows(data, 0);
+ * //-- [['john', 23, 'purple']];
+ * 
+ * utils.array.pickRows(data, 0, 1);
+ * //-- [['john', 23, 'purple'], ['jane', 32, 'red']];
+ */
+module.exports.pickRows = function pickRows(array2d, ...rowIndices) {
+  //-- allow passing an array as the first item
+  const cleanRowIndices = rowIndices.length > 0 && Array.isArray(rowIndices[0])
+    ? rowIndices[0]
+    : rowIndices;
+  return cleanRowIndices.map((index) => array2d[index]);
+};
+
+/**
+ * Picks a column (or multiple columns) from a 2d array
+ * 
+ * Please also see [Danfo.js](https://danfo.jsdata.org/) for working with DataFrames.
+ * 
+ * @param {Array} array2d - 2d array to pick from [row][column]
+ * @param  {...any} columns - Indexes of the columns to pick the values from: [0...row.length-1]
+ * @returns - Array with all rows, and only those columns
+ * @example
+ * data = [
+ *  ['john', 23, 'purple'],
+ *  ['jane', 32, 'red'],
+ *  ['ringo', 27, 'green']
+ * ];
+ * 
+ * utils.array.pickColumns(data, 0);
+ * //-- [['john'], ['jane'], ['ringo']];
+ * 
+ * utils.array.pickColumns(data, 0, 2);
+ * //-- [['john', 'purple'], ['jane', 'red'], ['ringo', 'green']];
+ */
+module.exports.pickColumns = function pickColumns(array2d, ...columns) {
+  //-- allow passing an array as the first item
+  const cleanColumns = columns.length > 0 && Array.isArray(columns[0])
+    ? columns[0]
+    : columns;
+  return array2d.map((row) => cleanColumns.map((columnIndex) => row[columnIndex]));
+};
+
+/**
+ * Convenience function for picking specific rows and columns from a 2d array.
+ * 
+ * Please also see [Danfo.js](https://danfo.jsdata.org/) for working with DataFrames.
+ * 
+ * @param {Array} array2d - 2d array to pick from [row][column]
+ * @param {Object} options - options on which to pick
+ * @param {Number[]} [options.rows = null] - indices of the rows to pick
+ * @param {Number[]} [options.columns = null] - indices of the columns to pick.
+ * @returns {Array} - 2d array of only the rows and columns chosen.
+ * @see {@link module:Array.pickRows} - picking rows
+ * @see {@link module:Array.pickColumns} - picking columns
+ * @returns - 2dArray of the columns and rows requested
+ * @example
+ * data = [
+ *  ['john', 23, 'purple'],
+ *  ['jane', 32, 'red'],
+ *  ['ringo', 27, 'green']
+ * ];
+ * 
+ * utils.array.pick(data, {rows: [0, 1]});
+ * //-- [['john', 23, 'purple'], ['jane', 32, 'red']];
+ * 
+ * utils.array.pick(data, {columns: [0, 2]});
+ * //-- [['john', 'purple'], ['jane', 'red'], ['ringo', 'green']];
+ * 
+ * utils.array.pick(data, {rows:[0, 1], columns:[0, 2]});
+ * //-- [['john', 'purple'], ['jane', 'red']];
+ */
+module.exports.pick = function pick(array2d, options) {
+  const cleanOptions = options || {};
+
+  const {
+    rows = null,
+    columns = null
+  } = cleanOptions;
+
+  let results = array2d;
+
+  if (rows) {
+    results = ArrayUtils.pickRows(results, rows);
+  }
+
+  if (columns) {
+    results = ArrayUtils.pickColumns(results, columns);
+  }
+
+  return results;
+};
+
 /**
  * Creates an array of a specific size and default value
  * 

package/src/datasets.js

@@ -9,6 +9,9 @@ const fetch = require('node-fetch');
  * The data lives at [https://github.com/vega/vega-datasets](https://github.com/vega/vega-datasets)
  * and [https://cdn.jsdelivr.net/npm/vega-datasets](https://cdn.jsdelivr.net/npm/vega-datasets)
  * 
+ * **For those of you familiar with Pandas, please consider looking at [danfo.js](https://danfo.jsdata.org/)
+ * and [DataFrame.js](https://gmousse.gitbooks.io/dataframe-js/content/#dataframe-js)**
+ * 
  * * {@link module:datasets.list|list()} - retrieves the list of the datasets available
  * * {@link module:datasets.fetch|fetch(datasetName)} - returns a promise and fetches the dataset
  * 

package/src/ijs.js

@@ -135,7 +135,7 @@ module.exports.await = async function ijsAsync(fn) {
   context.$$.async();
 
   try {
-    const results = fn(context.$$, context.console);
+    const results = await fn(context.$$, context.console);
     context.$$.sendResult(results);
   } catch (err) {
     context.console.error('error occurred');

package/src/latex.js

@@ -95,7 +95,7 @@ module.exports.render = function render(body) {
  * For example, here we can give options on display options, and additional custom macros.
  * 
  * ```
- * utils.katex.render("c = \\pm\\root{a^2 + b^2}\\in\\RR", {
+ * utils.latex.katex("c = \\pm\\root{a^2 + b^2}\\in\\RR", {
  *     displayMode: false,
  *     macros: {
  *       "\\RR": "\\mathbb{R}",