Skip to content

Commit 5596f18

Browse files
badosabadosa
committed
1.6.0
Includes new Unflatten() method
1 parent dcdd157 commit 5596f18

File tree

12 files changed

+325
-81
lines changed

12 files changed

+325
-81
lines changed

‎docs/API.md‎

Lines changed: 192 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -9,58 +9,60 @@
99
### By type
1010

1111
<ul>
12-
<li><strong><a href="#reading">Reading</a></strong>: <a href="#jsonstat">JSONstat()</a></li>
13-
<li><strong><a href="#traversing">Traversing</a></strong>: <a href="#dataset">Dataset()</a>, <a href="#dimension">Dimension()</a>, <a href="#category">Category()</a>, <a href="#data">Data()</a>, <a href="#item">Item()</a></li>
14-
<li><strong><a href="#transforming">Transforming</a></strong>: <a href="#totable">toTable()</a>, <a href="#dice">Dice()</a>, <a href="#slice">Slice()</a></li>
12+
<li><strong><a href="#reading">Reading</a></strong>: <a href="#jsonstat">JSONstat()</a></li>
13+
<li><strong><a href="#traversing">Traversing</a></strong>: <a href="#dataset">Dataset()</a>, <a href="#dimension">Dimension()</a>, <a href="#category">Category()</a>, <a href="#data">Data()</a>, <a href="#item">Item()</a></li>
14+
<li><strong><a href="#transforming">Transforming</a></strong>: <a href="#unflatten">Unflatten()</a>, <a href="#totable">toTable()</a>, <a href="#dice">Dice()</a>, <a href="#slice">Slice()</a></li>
1515
</ul>
1616

1717
### By hierarchy
1818

1919
<ul>
20-
<li><strong><a href="#jsonstat">JSONstat()</a></strong>:</li>
21-
<ul>
22-
<li>
23-
Collection responses: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#updated">updated</a>, <a href="#source">source</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
24-
<ul>
25-
<li>
26-
<strong><a href="#item">Item()</a></strong>: <a href="#class">class</a>, <a href="#href">href</a>, <a href="#label">label</a>, <a href="#extension">extension</a>
27-
</li>
28-
</ul>
29-
</li>
30-
<li>
31-
Bundle responses: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#error">error</a>
32-
<ul>
33-
<li><strong><a href="#dataset">Dataset()</a></strong>: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>,
34-
<a href="#label">label</a>, <a href="#n">n</a>, <a href="#size">size</a>, <a href="#value">value</a>, <a href="#status">status</a>, <a href="#updated">updated</a>, <a href="#source">source</a>, <a href="#role">role</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
35-
<ul>
36-
<li><strong><a href="#dimension">Dimension()</a></strong>: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#role">role</a>, <a href="#hierarchy">hierarchy</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
37-
<ul>
38-
<li><strong><a href="#category">Category()</a></strong>: <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#coordinates">coordinates</a>, <a href="#unit">unit</a>, <a href="#note">note</a></li>
39-
</ul>
40-
</li>
41-
<li><strong><a href="#data">Data()</a></strong>: <a href="#value">value</a>, <a href="#status">status</a></li>
42-
<li><strong><a href="#totable">toTable()</a></strong>
43-
<li><strong><a href="#dice">Dice()</a></strong>
44-
<li><strong><a href="#slice">Slice()</a></strong>
45-
</ul>
46-
</li>
47-
</ul>
48-
</li>
49-
<li>Dataset responses: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#n">n</a>, <a href="#size">size</a>, <a href="#value">value</a>, <a href="#status">status</a>, <a href="#updated">updated</a>, <a href="#source">source</a>, <a href="#role">role</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
50-
<ul>
51-
<li><strong><a href="#dimension">Dimension()</a></strong>: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#role">role</a>, <a href="#hierarchy">hierarchy</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
52-
<ul>
53-
<li><strong><a href="#category">Category()</a></strong>: <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#coordinates">coordinates</a>, <a href="#unit">unit</a>, <a href="#note">note</a></li>
54-
</ul>
55-
</li>
56-
<li><strong><a href="#data">Data()</a></strong>: <a href="#value">value</a>, <a href="#status">status</a></li>
57-
<li><strong><a href="#totable">toTable()</a></strong>
58-
<li><strong><a href="#dice">Dice()</a></strong>
59-
<li><strong><a href="#slice">Slice()</a></strong>
60-
</ul>
61-
</li>
62-
</ul>
63-
</li>
20+
<li><strong><a href="#jsonstat">JSONstat()</a></strong>:</li>
21+
<ul>
22+
<li>
23+
Collection responses: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#updated">updated</a>, <a href="#source">source</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
24+
<ul>
25+
<li>
26+
<strong><a href="#item">Item()</a></strong>: <a href="#class">class</a>, <a href="#href">href</a>, <a href="#label">label</a>, <a href="#extension">extension</a>
27+
</li>
28+
</ul>
29+
</li>
30+
<li>
31+
Bundle responses: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#error">error</a>
32+
<ul>
33+
<li><strong><a href="#dataset">Dataset()</a></strong>: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>,
34+
<a href="#label">label</a>, <a href="#n">n</a>, <a href="#size">size</a>, <a href="#value">value</a>, <a href="#status">status</a>, <a href="#updated">updated</a>, <a href="#source">source</a>, <a href="#role">role</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
35+
<ul>
36+
<li><strong><a href="#dimension">Dimension()</a></strong>: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#role">role</a>, <a href="#hierarchy">hierarchy</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
37+
<ul>
38+
<li><strong><a href="#category">Category()</a></strong>: <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#coordinates">coordinates</a>, <a href="#unit">unit</a>, <a href="#note">note</a></li>
39+
</ul>
40+
</li>
41+
<li><strong><a href="#data">Data()</a></strong>: <a href="#value">value</a>, <a href="#status">status</a></li>
42+
<li><strong><a href="#unflatten">Unflatten()</a></strong></li>
43+
<li><strong><a href="#totable">toTable()</a></strong></li>
44+
<li><strong><a href="#dice">Dice()</a></strong></li>
45+
<li><strong><a href="#slice">Slice()</a></strong></li>
46+
</ul>
47+
</li>
48+
</ul>
49+
</li>
50+
<li>Dataset responses: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#n">n</a>, <a href="#size">size</a>, <a href="#value">value</a>, <a href="#status">status</a>, <a href="#updated">updated</a>, <a href="#source">source</a>, <a href="#role">role</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
51+
<ul>
52+
<li><strong><a href="#dimension">Dimension()</a></strong>: <a href="#class">class</a>, <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#role">role</a>, <a href="#hierarchy">hierarchy</a>, <a href="#note">note</a>, <a href="#href">href</a>, <a href="#link">link</a>, <a href="#extension">extension</a>
53+
<ul>
54+
<li><strong><a href="#category">Category()</a></strong>: <a href="#length">length</a>, <a href="#id">id</a>, <a href="#label">label</a>, <a href="#coordinates">coordinates</a>, <a href="#unit">unit</a>, <a href="#note">note</a></li>
55+
</ul>
56+
</li>
57+
<li><strong><a href="#data">Data()</a></strong>: <a href="#value">value</a>, <a href="#status">status</a></li>
58+
<li><strong><a href="#unflatten">Unflatten()</a></strong></li>
59+
<li><strong><a href="#totable">toTable()</a></strong></li>
60+
<li><strong><a href="#dice">Dice()</a></strong></li>
61+
<li><strong><a href="#slice">Slice()</a></strong></li>
62+
</ul>
63+
</li>
64+
</ul>
65+
</li>
6466
</ul>
6567

6668
## Public Properties
@@ -407,6 +409,139 @@ JSONstat( "https://json-stat.org/samples/collection.json" ).then(function(j) {
407409

408410
## Transforming
409411

412+
### Unflatten()
413+
414+
***
415+
<div><strong>Parent</strong>: <a href="#dataset">Dataset</a></div>
416+
<div><strong>Description</strong>: Converts information from a <em>jsonstat</em> instance into a data array with the associated dimension categories</div>
417+
<div><strong>Public Properties</strong>: &mdash;</div>
418+
<div><strong>Summary</strong>: <code><i>array</i> Unflatten ( <i>function</i> callback )</code></div>
419+
420+
***
421+
422+
Added in version 1.6, this method is more efficient and flexible than <a href="#totable">toTable()</a>. While <a href="#totable">toTable()</a> supports popular structures and transformations, Unflatten uses a better extraction method to expose data and its associated metadata to a callback function allowing the user to customize the resulting output.
423+
424+
#### Parameters
425+
##### callback (required)
426+
427+
It is a function that defines the structure of the returned array.
428+
429+
Unflatten returns an array that exposes the following cell-level information to the callback function:
430+
431+
* **Coordinates**: An object describing the location of the cell in the cube in terms of dimension ids and category ids.
432+
433+
```json
434+
{
435+
"sex": "M",
436+
"concept": "POP",
437+
"age": "T",
438+
"year": "2012",
439+
"country": "CA"
440+
}
441+
```
442+
443+
* **Data point**: An object with the cell value and status (when no status information is available, "status" will be set to *null*).
444+
445+
```json
446+
{
447+
"value": 17309.1,
448+
"status": "a"
449+
}
450+
```
451+
452+
* **Cell counter**: An integer expressing the position of the cell in the array of values.
453+
454+
* **Cells array**: The returned array.
455+
456+
#### Return Value
457+
458+
It returns an array. If no callback function is provided, *null* is returned.
459+
460+
```js
461+
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
462+
//It returns an array of objects with two properties: "coordinates" and "datapoint"
463+
const arr1=j.Unflatten((coordinates, datapoint) => {
464+
return {coordinates, datapoint};
465+
});
466+
467+
//"coordinates" and "value"
468+
const arr2=j.Unflatten((coordinates, datapoint) => {
469+
return {coordinates, value: datapoint.value};
470+
});
471+
472+
//Array of flat objects that use dimension and category ids and value
473+
const arr3=j.Unflatten((coordinates, datapoint) => {
474+
const ret={};
475+
476+
j.id.forEach(dimId => {
477+
ret[dimId] = coordinates[dimId];
478+
});
479+
480+
ret.value = datapoint.value;
481+
482+
return ret;
483+
});
484+
485+
//Array of flat objects including "status" and using dimension and category labels instead of ids
486+
const arr4=j.Unflatten((coordinates, datapoint) => {
487+
const ret={};
488+
489+
j.id.forEach(dimId => {
490+
const dim = j.Dimension(dimId);
491+
ret[dim.label] = dim.Category(coordinates[dimId]).label;
492+
});
493+
494+
ret.value = datapoint.value;
495+
ret.status = datapoint.status;
496+
497+
return ret;
498+
});
499+
500+
//CSV string with value and status
501+
const csv1=j.Unflatten((coordinates, datapoint, n, row) => {
502+
const
503+
dimIds = j.id
504+
ret={}
505+
;
506+
507+
if(n===0){
508+
row.push(dimIds.join(',').concat(',value,status'));
509+
}
510+
511+
dimIds.forEach(dimId => {
512+
ret[dimId] = coordinates[dimId];
513+
});
514+
515+
ret.value = datapoint.value;
516+
ret.status = datapoint.status;
517+
518+
return Object.values(ret).join(',');
519+
}).join('\n');
520+
521+
//Filtered CSV string (only females)
522+
const csv2=j.Unflatten((coordinates, datapoint, n, row) => {
523+
const
524+
dimIds = j.id,
525+
ret={}
526+
;
527+
528+
if(n===0){
529+
row.push(dimIds.join(',').concat(',value,status'));
530+
}
531+
dimIds.forEach(dimId => {
532+
ret[dimId] = coordinates[dimId];
533+
});
534+
ret.value = datapoint.value;
535+
ret.status = datapoint.status;
536+
537+
if(coordinates.sex === 'F'){
538+
return Object.values(ret).join(',');
539+
}
540+
}).join('\n');
541+
542+
});
543+
```
544+
410545
### toTable()
411546

412547
***
@@ -417,6 +552,8 @@ JSONstat( "https://json-stat.org/samples/collection.json" ).then(function(j) {
417552

418553
***
419554

555+
For a more efficient and more flexible transformation method, see <a href="#unflatten">Unflatten()</a>.
556+
420557
#### Parameters
421558

422559
##### opts
@@ -471,7 +608,7 @@ Even though toTable can expose a table using different structures depending on *
471608
```js
472609
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
473610
//Discard data by age in the resulting table
474-
j.toTable(
611+
const arrobj=j.toTable(
475612
{ type : "arrobj" },
476613
function( d, i ){
477614
if( d.age==="total" ){
@@ -488,7 +625,7 @@ Filters and transformations in the **callback** must be expressed in terms of th
488625
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
489626
//Discard data by age in the resulting table.
490627
//Using categories ID instead of labels.
491-
j.toTable(
628+
const arrobj=j.toTable(
492629
{ type : "arrobj" , content : "id" },
493630
function( d, i ){
494631
if( d.age==="T" ){
@@ -505,7 +642,7 @@ Take into account that every **type** returns a different form of data array.
505642
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
506643
//As previous example but with type "array"
507644
//Age is the third dimension (its index is 2)
508-
j.toTable(
645+
const arr=j.toTable(
509646
{ type : "array" , content : "id" },
510647
function( d, i ){
511648
if( d[2]==="T" ){
@@ -520,7 +657,7 @@ JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
520657
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
521658
//As previous example but with type "object"
522659
//Age is the third dimension (its index is 2)
523-
j.toTable(
660+
const obj=j.toTable(
524661
{ type : "object" , content : "id" },
525662
function( d, i ){
526663
if( d.c[2].v==="T" ){
@@ -536,7 +673,7 @@ The *arrobj* / *objarr* **types** do not return a table header, but *array* and
536673
```js
537674
JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
538675
//This will not remove the header (row 0 in type "array") but the first data row
539-
j.toTable(
676+
const arr=j.toTable(
540677
{ type : "array" },
541678
function( d, i ){
542679
if( i ){
@@ -556,7 +693,7 @@ JSONstat( "https://json-stat.org/samples/canada.json" ).then(function(j) {
556693
//Select only the female population by age group
557694
//Get an array of objects with only two properties (age and population)
558695
//Change scale of units
559-
j.toTable(
696+
const arrobj=j.toTable(
560697
{ type : "arrobj", content : "id" },
561698
function( d ){
562699
if( d.sex==="F" && d.concept==="POP" ){
@@ -675,6 +812,8 @@ It returns an object of arrays in the [Google DataTable](https://developers.goog
675812

676813
***
677814

815+
Added in version 1.1.
816+
678817
#### Parameters
679818

680819
##### filter

‎docs/EXAMPLES.md‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,6 @@
2626

2727
### Retrieving JJT's version
2828

29-
Example: [JJT v1 vs v0 "version"](https://bl.ocks.org/badosa/73097b82e22f1b06522b4437b1112878)
30-
3129
#### Version 0
3230

3331
```js
@@ -42,8 +40,6 @@ var version=JSONstat("version");
4240

4341
### Doing a GET request
4442

45-
Example: [JJT v1: GET request](https://bl.ocks.org/badosa/ddd1b3783800dffa9cf7426f6042cc83)
46-
4743
#### Version 0
4844

4945
```js
@@ -69,8 +65,6 @@ function main(j){
6965

7066
### Doing a POST request
7167

72-
Example: [JJT v1: POST request](https://bl.ocks.org/badosa/9aecb97692d743eff6734e3a34fbc4e9)
73-
7468
#### Version 0
7569

7670
Not supported.
@@ -93,8 +87,6 @@ function main(j){
9387

9488
### ECMAScript Module
9589

96-
Example: [JJT v1: ECMAScript module](https://bl.ocks.org/badosa/c1feb27bd8214de60f430379424e12fa)
97-
9890
#### Version 0
9991

10092
```html
@@ -118,8 +110,6 @@ Example: [JJT v1: ECMAScript module](https://bl.ocks.org/badosa/c1feb27bd8214de6
118110

119111
### IE Support for JSONstat requests
120112

121-
Example: [JJT v1: GET request](https://bl.ocks.org/badosa/ddd1b3783800dffa9cf7426f6042cc83)
122-
123113
#### Version 0
124114

125115
```html

0 commit comments

Comments
 (0)