jupyter-ijavascript-utils 1.0.1 → 1.1.2

package/.eslintrc.js

@@ -29,5 +29,7 @@ module.exports = {
     'lines-between-class-members': 'off',
     'no-unneeded-ternary': 'off',
     'no-else-return': ['error', { allowElseIf: true }],
+    'implicit-arrow-linebreak': 'off',
+    'max-len': ['error', { code: 150 }]
   }
 };

package/.screenrc

@@ -19,8 +19,6 @@ screen -t "jsUtils"
 screen -p jsUtils -X stuff "cd ../jupyterJsUtils^M"
 screen -t "scratchpad"
 screen -p scratchpad -X stuff "cd ../jupyterScratchpad^M"
-screen -t "p4js"
-screen -p p4js -X stuff "cd '../python-for-js-developers'^M"
 
 screen -t lint
 screen -p lint -X stuff "npm run lint:watch"
@@ -28,6 +26,11 @@ screen -t test
 screen -p test -X stuff "npm run test:watch"
 screen -t debug
 
+screen -t "transfer"
+screen -p transfer -X stuff "cd ../transfer"
+screen -t "p4js"
+screen -p p4js -X stuff "cd '../python-for-js-developers'^M"
+
 screen -t "server" 10
 screen -p server -X stuff "cd ../^Mjupyter lab"
 screen -t plantuml 11

package/.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Attach",
+            "port": 9229,
+            "request": "attach",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "type": "pwa-node"
+        }
+    ]
+}

package/DOCS.md

@@ -4,62 +4,163 @@ This is a simple Library for using Jupyter with the IJavaScript kernel
 
 See the [#Installation section for requirements and installation](#install)
 
-| Export | Description                                                                      |
-|-----------|----------------------------------------------------------------------------------|
-| [ijs](./IJSUtils.html)       | Utility methods to support working within the iJavaScript kernel within Jupyter. |
-| [datasets](./module-datasets.html)  | Utilities to facilitate working with example datasets provided by vega.          |
-| [vega](./module-vega.html)      | Simple utility to streamline showing Vega-Lite charts within iJS Notebooks.      |
+| Export | Description                                                                                                                |
+|-------------------------------|-----------------------------------------------------------------------------------------------------|
+| {@link module:aggregate}      | Aggregating formulas for reducing collections of records.                                           |
+| {@link module:array}          | Utilities for massaging, sorting, reshaping and working with arrays.                                |
+| {@link module:base64}         | Utilities to convert to and from base64 encoding of strings                                         |
+| {@link module:datasets}       | Utilities to facilitate working with example datasets provided by the vega team                     |
+| {@link module:file}           | Utilities reading and writing data and text to files.                                               |
+| {@link module:format}         | Utilities for formatting and massaging data to be legible.                                          |
+| {@link module:group}          | Library to group collections of objects - generating Maps of records ({@link SourceMap})            |
+| {@link module:ijs}            | Utility methods to support working within the iJavaScript kernel within Jupyter.                    |
+| {@link module:object}         | Utilities for massaging and managing JavaScript Objects or collections of Objects.                  |
+| {@link module:set}            | Functional Utilities for managing JavaScript Sets - allowing for chaining.                          |
+| {@link module:vega}           | Simple utility to streamline showing Vega-Lite charts within iJS Notebooks.                         |
+| {@link SourceMap}             | SubClass of Maps - generated by the {@link module:group} and reducible with {@link module:aggregate} |
+| {@link TableGenerator}        | Class that can filter, sorts, manage and then generate HTML, CSV, Markdown, etc.                    |
 
 -------
 
-## For Example
+# For Example
+
+## Get Sample Data
+
+({@link module:datasets|See the DataSets module for more on sample datasets})
+
+({@link module:ijs.await|See the ijs module for helpers to use async/await})
 
 ```
 //-- get the data
-utils.dataset.fetch('barley.json').then((data) => barley = data);
+utils.ijs.await(async ($$, console) => {
+	barley = await utils.datasets.fetch('barley.json');
+
+	//-- continue to use the barley dataset, or wait to the next cell
+});
+```
+
+## Group By
 
+Then we can group using a process similar to d3js
+
+({@link module:group|see the Group module for more on grouping})
+
+```
 //-- get the min max of the types of barley
-barleyByVarietySite = d3.group(barley, d => d.variety, d => d.site)
+barleyByVarietySite = utils.group.by(barley, 'variety', 'site')
 
-// InternMap(10) [Map] {
-//   'Manchuria' => InternMap(6) [Map] {
+// SourceMap(10) [Map] {
+//   'Manchuria' => SourceMap(6) [Map] {
+//     'University Farm' => [ [Object], [Object] ],
+//     'Waseca' => [ [Object], [Object] ],
+//     'Morris' => [ [Object], [Object] ],
+//     'Crookston' => [ [Object], [Object] ],
+//     'Grand Rapids' => [ [Object], [Object] ],
+//     'Duluth' => [ [Object], [Object] ],
+//     source: 'site'
+//   },
+//   'Glabron' => SourceMap(6) [Map] {
 //     'University Farm' => [ [Object], [Object] ],
 //     'Waseca' => [ [Object], [Object] ],
-//     ...
-//   }, ...
+//     'Morris' => [ [Object], [Object] ],
+//     'Crookston' => [ [Object], [Object] ],
+//     'Grand Rapids' => [ [Object], [Object] ],
+//     'Duluth' => [ [Object], [Object] ],
+//     source: 'site'
+//   },
+//   ...
 // }
 
 //-- now group by variety and year
-barleyByVarietyYear = d3.group(barley, d => d.variety, d => d.year)
-
-// nternMap(10) [Map] {
-//  'Manchuria' => InternMap(2) [Map] {
-//    1931 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
-//    1932 => [ [Object], [Object], [Object], [Object], [Object], [Object] ]
-//  }, ...
-// 
+barleyByVarietyYear = utils.group.by(barley, 'variety', 'year')
+
+// SourceMap(10) [Map] {
+//   'Manchuria' => SourceMap(2) [Map] {
+//     1931 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//     1932 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//     source: 'year'
+//   },
+//   'Glabron' => SourceMap(2) [Map] {
+//     1931 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//     1932 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//     source: 'year'
+//   },
+//   ...
+// }
 ```
 
-[note: See here to learn more about d3 grouping](https://observablehq.com/@d3/d3-group)
+##  Aggregating
 
-then later
+({@link module:aggregate|See the Aggregation module for more})
 
 ```
-utils.ijs.listGlobals();
-// ['barley','d3','barleyByVariety','barleyByVarietySite',...]
+utils.group.by(barley, 'variety', 'site')
+    .reduce((collection) => ({
+        years: utils.aggregate.extent(collection, 'year'),
+        numRecords: utils.aggregate.length(collection),
+        yield_sum: utils.aggregate.sum(collection, 'yield'),
+        yield_min: utils.aggregate.min(collection, 'yield'),
+        yield_max: utils.aggregate.max(collection, 'yield'),
+        yield_diff: utils.aggregate.difference(collection, 'yield')
+    }));
+
+returns
+[
+  {
+    variety: 'Manchuria',
+    site: 'University Farm',
+    years: { min: 1931, max: 1932 },
+    numRecords: 2,
+    yield_sum: 53.9,
+    yield_min: 26.9,
+    yield_max: 27,
+    yield_diff: 0.100
+  },
+  {
+    variety: 'Manchuria',
+    site: 'Waseca',
+    years: { min: 1931, max: 1932 },
+    numRecords: 2,
+    yield_sum: 82.33333,
+    yield_min: 33.46667,
+    yield_max: 48.86667,
+    yield_diff: 15.39999
+  },
+  ...
+];
 ```
 
-now show a graph
+## Render as a Table
+
+({@link TableGenerator|See the TableGenerator class for more})
 
 ```
-utils.vega.svg($$, utils.vega.markPoint()
+new utils.TableGenerator(barley)
+    .sort('-yield')
+    .formatter({ year: (v) => `${v}`})
+    .limit(10)
+    .render()
+```
+
+![Screenshot of table](img/BarleySimpleTable.png)
+
+## Show a Graph
+
+({@link module:vega|See the Aggregation module for more})
+
+or
+
+([See the Vega tutorial]{@tutorial vega1})
+
+```
+utils.vega.svg((vl) => vl.markPoint()
     .data(barley)
     .title('Barley Yield by Site')
     .width(600)
     .encode(
-        utils.vega.x().fieldN('site'),
-        utils.vega.y().fieldQ('yield'),
-        utils.vega.color().fieldN('year')
+        vl.x().fieldN('site'),
+        vl.y().fieldQ('yield'),
+        vl.color().fieldN('year')
     )
 )
 ```
@@ -77,3 +178,5 @@ Depends on:
 
 * [Jupyter Tools - such as Jupyter Lab](https://jupyter.org/)
 * [n-riesco/ijavascript jupyter kernel](https://github.com/n-riesco/ijavascript#installation)
+
+See the [How to Use]{@tutorial howToUse} section for more.

package/README.md

@@ -5,70 +5,156 @@
     <a href="https://jupyter-ijavascript-utils.onrender.com/LICENSE" alt="License">
         <img src="https://img.shields.io/badge/License-MIT-green" />
     </a>
+    <img src="https://img.shields.io/badge/Coverage-98-green" />
 </p>
 
 # Overview
 
 Simple library for working with Jupyter - through IJavaScript kernel.
 
-## For Example
+# Documentation
+
+See documentation at: [https://jupyter-ijavascript-utils.onrender.com/](https://jupyter-ijavascript-utils.onrender.com/)
+
+# For Example
+
+## Get Sample Data
+
+({@link module:datasets|See the DataSets module for more on sample datasets})
+
+({@link module:ijs.await|See the ijs module for helpers to use async/await})
 
 ```
 //-- get the data
-utils.dataset.fetch('barley.json').then((data) => barley = data);
+utils.ijs.await(async ($$, console) => {
+	barley = await utils.datasets.fetch('barley.json');
 
+	//-- continue to use the barley dataset, or wait to the next cell
+});
+```
+
+## Group By
+
+Then we can group using a process similar to d3js
+
+({@link module:group|see the Group module for more on grouping})
+
+```
 //-- get the min max of the types of barley
-barleyByVarietySite = d3.group(barley, d => d.variety, d => d.site)
+barleyByVarietySite = utils.group.by(barley, 'variety', 'site')
 
-// InternMap(10) [Map] {
-//   'Manchuria' => InternMap(6) [Map] {
+// SourceMap(10) [Map] {
+//   'Manchuria' => SourceMap(6) [Map] {
+//     'University Farm' => [ [Object], [Object] ],
+//     'Waseca' => [ [Object], [Object] ],
+//     'Morris' => [ [Object], [Object] ],
+//     'Crookston' => [ [Object], [Object] ],
+//     'Grand Rapids' => [ [Object], [Object] ],
+//     'Duluth' => [ [Object], [Object] ],
+//     source: 'site'
+//   },
+//   'Glabron' => SourceMap(6) [Map] {
 //     'University Farm' => [ [Object], [Object] ],
 //     'Waseca' => [ [Object], [Object] ],
-//     ...
-//   }, ...
+//     'Morris' => [ [Object], [Object] ],
+//     'Crookston' => [ [Object], [Object] ],
+//     'Grand Rapids' => [ [Object], [Object] ],
+//     'Duluth' => [ [Object], [Object] ],
+//     source: 'site'
+//   },
+//   ...
 // }
 
 //-- now group by variety and year
-barleyByVarietyYear = d3.group(barley, d => d.variety, d => d.year)
-
-// nternMap(10) [Map] {
-//  'Manchuria' => InternMap(2) [Map] {
-//    1931 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
-//    1932 => [ [Object], [Object], [Object], [Object], [Object], [Object] ]
-//  }, ...
-// 
+barleyByVarietyYear = utils.group.by(barley, 'variety', 'year')
+
+// SourceMap(10) [Map] {
+//   'Manchuria' => SourceMap(2) [Map] {
+//     1931 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//     1932 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//     source: 'year'
+//   },
+//   'Glabron' => SourceMap(2) [Map] {
+//     1931 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//     1932 => [ [Object], [Object], [Object], [Object], [Object], [Object] ],
+//     source: 'year'
+//   },
+//   ...
+// }
+```
+
+##  Aggregating
+
+({@link module:aggregate|See the Aggregation module for more})
+
+```
+utils.group.by(barley, 'variety', 'site')
+    .reduce((collection) => ({
+        years: utils.aggregate.extent(collection, 'year'),
+        numRecords: utils.aggregate.length(collection),
+        yield_sum: utils.aggregate.sum(collection, 'yield'),
+        yield_min: utils.aggregate.min(collection, 'yield'),
+        yield_max: utils.aggregate.max(collection, 'yield'),
+        yield_diff: utils.aggregate.difference(collection, 'yield')
+    }));
+
+returns
+[
+  {
+    variety: 'Manchuria',
+    site: 'University Farm',
+    years: { min: 1931, max: 1932 },
+    numRecords: 2,
+    yield_sum: 53.9,
+    yield_min: 26.9,
+    yield_max: 27,
+    yield_diff: 0.100
+  },
+  {
+    variety: 'Manchuria',
+    site: 'Waseca',
+    years: { min: 1931, max: 1932 },
+    numRecords: 2,
+    yield_sum: 82.33333,
+    yield_min: 33.46667,
+    yield_max: 48.86667,
+    yield_diff: 15.39999
+  },
+  ...
+];
 ```
 
-[note: See here to learn more about d3 grouping](https://observablehq.com/@d3/d3-group)
+## Render as a Table
 
-then later
+({@link TableGenerator|See the TableGenerator class for more})
 
 ```
-utils.ijs.listGlobals();
-// ['barley','d3','barleyByVariety','barleyByVarietySite',...]
+new utils.TableGenerator(barley)
+    .sort('-yield')
+    .formatter({ year: (v) => `${v}`})
+    .limit(10)
+    .render()
 ```
 
+![Screenshot of table](https://jupyter-ijavascript-utils.onrender.com/img/BarleySimpleTable.png)
+
 now show a graph
 
 ```
-utils.vega.svg($$, utils.vega.markPoint()
+utils.vega.svg((vl) => vl.markPoint()
     .data(barley)
     .title('Barley Yield by Site')
     .width(600)
     .encode(
-        utils.vega.x().fieldN('site'),
-        utils.vega.y().fieldQ('yield'),
-        utils.vega.color().fieldN('year')
+        vl.x().fieldN('site'),
+        vl.y().fieldQ('yield'),
+        vl.color().fieldN('year')
     )
 )
 ```
 
 ![Screenshot of Vega Cell](https://jupyter-ijavascript-utils.onrender.com/img/BarleyYieldBySite.png)
 
-# Documentation
-
-See documentation at: [https://jupyter-ijavascript-utils.onrender.com/](https://jupyter-ijavascript-utils.onrender.com/)
-
 # License
 
 See [License](https://jupyter-ijavascript-utils.onrender.com/LICENSE) (MIT License).
@@ -77,6 +163,10 @@ See [License](https://jupyter-ijavascript-utils.onrender.com/LICENSE) (MIT Licen
 
 If you have any questions first file it on [issues](https://github.com/paulroth3d/jupyter-ijavascript-utils/issues) before contacting authors.
 
+## Toubleshooting
+
+iJavaScript does not currently support AMD Modules, due to open issues with nodejs [see iJavaScript issue #210 for more](https://github.com/n-riesco/ijavascript/issues/210)
+
 # Contributions
 
 Your contributions are welcome: both by reporting issues on [GitHub issues](https://github.com/paulroth3d/jupyter-ijavascript-utils/issues) or pull-requesting patches.
@@ -92,3 +182,8 @@ If your feature implementation is brand-new or fixing unsupposed bugs in the lib
 * [DocDash Template](http://clenemt.github.io/docdash/)
 * [DocDash Example Code](http://clenemt.github.io/docdash/base_chains.js.html)
 * [Gist creating JSDoc to MD](https://gist.github.com/slorber/0bf8c8c8001505f0f99a062ac55bf442)
+* [JSDoc Documentation](https://jsdoc.app/index.html)
+* [D3 Grouping / Data Transformation](https://observablehq.com/@d3/d3-group)
+* [Danfo](https://danfo.jsdata.org/api-reference/plotting/tables)
+* [DataFrame-js](https://github.com/Gmousse/dataframe-js)
+* [ES21 array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat)

package/TODO.md

@@ -0,0 +1,33 @@
+[X] finish tutorials
+  [X] How to get Jupyter iJavaScript setup
+  [X] Example massaging data to create a table and chart
+  [ ] Finish example walkthrough
+[X] update the docs file index`
+[X] check there is an index for all modules and classes
+	[X] aggregate
+	[X] array
+	[X] base64
+	[X] datasets
+	[X] file
+	[X] format
+	[X] group
+	[X] ijs
+	[X] object
+	[X] set
+	[X] vega
+	[X] SourceMap
+	[X] TableGenerator
+[ ] check there are examples for all the methods
+	[ ] aggregate
+	[ ] array
+	[ ] base64
+	[ ] datasets
+	[ ] file
+	[ ] format
+	[ ] group
+	[ ] ijs
+	[ ] object
+	[ ] set
+	[ ] vega
+	[ ] SourceMap
+	[ ] TableGenerator

package/docResources/docdash/layout.tmpl

@@ -0,0 +1,99 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <?js if (!env.conf.docdash) { env.conf.docdash = {};} ?>
+    <meta charset="utf-8">
+    <title><?js= title ?> - <?js= ((env.conf.docdash.meta && env.conf.docdash.meta.title) || "Documentation") ?></title>
+    <?js if (env.conf.docdash.meta) { ?>
+    <?js if (env.conf.docdash.meta.description) { ?><meta name="description" content="<?js= env.conf.docdash.meta.description ?>" /><?js } ?>
+    <?js if (env.conf.docdash.meta.keyword) { ?>
+        <meta name="keywords" content="<?js= env.conf.docdash.meta.keyword ?>" />
+        <meta name="keyword" content="<?js= env.conf.docdash.meta.keyword ?>" />
+    <?js } ?>
+    <?js } ?>
+    <?js if (env.conf.docdash.openGraph) { ?>
+    <meta property="og:title" content="<?js= env.conf.docdash.openGraph.title ?>"/>
+    <meta property="og:type" content="<?js= env.conf.docdash.openGraph.type ?>"/>
+    <meta property="og:image" content="<?js= env.conf.docdash.openGraph.image ?>"/>
+    <?js if (env.conf.docdash.openGraph.site_name) { ?><meta property="og:site_name" content="<?js= env.conf.docdash.openGraph.site_name ?>"/><?js } ?>
+    <meta property="og:url" content="<?js= env.conf.docdash.openGraph.url ?>"/>
+    <?js } ?>
+    <script src="scripts/prettify/prettify.js"></script>
+    <script src="scripts/prettify/lang-css.js"></script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
+    <script src="scripts/nav.js" defer></script>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="icon" type="image/svg+xml" href="favicon.svg">
+    <link rel="icon" type="image/png" href="favicon.png">
+</head>
+<body>
+
+<input type="checkbox" id="nav-trigger" class="nav-trigger" />
+<label for="nav-trigger" class="navicon-button x">
+  <div class="navicon"></div>
+</label>
+
+<label for="nav-trigger" class="overlay"></label>
+
+<nav <?js if (env.conf.docdash.wrap) { ?>class="wrap"<?js } ?>>
+    <?js if (env.conf.docdash.search) { ?>
+    <input type="text" id="nav-search" placeholder="Search" />
+    <?js } ?>
+    <?js= this.nav ?>
+</nav>
+
+<div id="main">
+    <?js if (title != 'Home') { ?>
+    <h1 class="page-title"><?js= title ?></h1>
+    <?js } ?>
+
+    <?js= content ?>
+    
+    <?js if (env.conf.docdash.disqus) { ?>
+    <div id="disqus_thread"></div>
+    <script>
+    (function() { // DON'T EDIT BELOW THIS LINE
+    var d = document, s = d.createElement('script');
+    s.src = '//<?js= env.conf.docdash.disqus ?>.disqus.com/embed.js';
+    s.setAttribute('data-timestamp', +new Date());
+    (d.head || d.body).appendChild(s);
+    })();
+    </script>
+    <noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
+    <?js } ?>
+</div>
+
+<br class="clear">
+
+<footer>
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc <?js= env.version.number ?></a><?js if(env.conf.templates && env.conf.templates.default && env.conf.templates.default.includeDate !== false) { ?> on <?js= (new Date()) ?><?js } ?> using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+</footer>
+
+<script>prettyPrint();</script>
+<script src="scripts/polyfill.js"></script>
+<script src="scripts/linenumber.js"></script>
+<?js if (env.conf.docdash.search) { ?>
+<script src="scripts/search.js" defer></script>
+<?js } ?>
+<?js if (env.conf.docdash.collapse) { ?>
+<script src="scripts/collapse.js" defer></script>
+<?js } ?>
+<?js if (env.conf.docdash.scripts && env.conf.docdash.scripts.length) {
+    for(var i = 0; i < env.conf.docdash.scripts.length; i++){
+        if (env.conf.docdash.scripts[i].indexOf(".css") != -1) {
+    ?>
+    <link type="text/css" rel="stylesheet" href="<?js= env.conf.docdash.scripts[i] ?>">
+    <?js
+        } else {
+    ?>
+    <script src="<?js= env.conf.docdash.scripts[i] ?>"></script>
+    <?js
+        }
+    }
+} ?>
+</body>
+</html>