JSON-stat & JS: the JSON-stat Javascript Toolkit

JSON-stat & JS
the JSON-stat Javascript Toolkit
Xavier Badosa
@badosa
https://xavierbadosa.com
https://json-stat.org
July, 2013
(updated to JSON-stat 2.0 in January, 2016)

The JSON-stat
Ecosystem
format
libs
conn.
schema

Introducing
the
JSON-stat
Javascript
Toolkit
json-stat.com

Introducing
the
JSON-stat
Javascript
Toolkit
It’s a Javascript
library that helps
you dealing with
JSON-stat
responses.

Introducing
the
JSON-stat
Javascript
Toolkit
It offers methods
to easily traverse
the JSON-stat
tree:
Dataset
Dimension
Category
Data

Introducing
the
JSON-stat
Javascript
Toolkit
It uses three
general
properties:
label
length
id

Sample file
the
JSON-stat
Javascript
Toolkit
This URL returns
a JSON-stat dataset
document.
(Collections can contain
several datasets.)
json-stat.org/samples/canada.json

var ds = JSONstat(
"http://json-stat.org/samples/canada.json"
);
if ( ds.length > 0 ) {
…
}
Retrieve a JSON-stat document.
Check the number of elements.
If zero, the service didn’t return
a valid JSON-stat response.
Sync

JSONstat(
"http://json-stat.org/samples/canada.json",
function () {
if ( this.length > 0 ) {
…
}
}
);
Retrieve a JSON-stat document.
Check the number of elements.
If zero, the service didn’t return
a valid JSON-stat response.
Async

$.getJSON(
"http://json-stat.org/samples/canada.json",
function ( obj ) {
var ds = JSONstat( obj );
if ( ds.length > 0 ) {
…
}
}
);
You can also retrieve a JSON-stat document
with your usual bullet-proof framework and
use JSONstat() for what is good for:
dealing with the resulting object.

var ds = JSONstat(
);
var cl = ds.class;
It contains a dataset (a cube).
ds.class → "dataset"

var ds = JSONstat(
);
var cl = ds.class;
(Because it’s a dataset response
you don’t need to use the Dataset() method.)
ds === ds.Dataset( 0 ) → true

var dslabel = ds.label;
Get the dataset label.
ds.label → "Population by sex and age group. Canada. 2012"

var nobs = ds.n;
var upd = ds.updated; // new Date(upd) to convert into date
Get the number of data in the dataset
and the update information.
ds.n → 120
ds.updated → "2012-09-27"

var nobs = ds.n;
var upd = ds.updated;
var ndim = ds.length;
var dimid = ds.id;
Get the number of dimensions and
the dimensions’ IDs.
ds.length → 5
ds.id → ["country", "year", "age", "concept", "sex"]

var nobs = ds.n;
var dimid = ds.id;
var sex = ds.Dimension( 4 );
Let’s analyze dimension “sex”.
Selected by index.

var nobs = ds.n;
var dimid = ds.id;
var sex = ds.Dimension( "sex" );
Let’s analyze dimension “sex”.
Selected by ID.

var nobs = ds.n;
var dimid = ds.id;
var sexsize = sex.length;
var sexid = sex.id;
sex.length is not what it seems: it’s just
the number of categories of dimension“sex”.
sex.length → 3
sex.id → ["T", "M", "F"]

var nobs = ds.n;
var dimid = ds.id;
var sexid = sex.id;
var sexlabel = sex.label;
As you can see, properties length, id and label
are everywhere.
sex.label → "sex"

var nobs = ds.n;
var dimid = ds.id;
var sexid = sex.id;
var sexlabel = sex.label;
var sexrole = sex.role;
sex is considered a classification variable because
the provider didn’t attach any special role to it.
sex.role → classification

var yearrole = ds.Dimension( "year" ).role;
var countryrole = ds.Dimension( "country" ).role;
Special roles are time, geo and metric.
ds.Dimension( "year" ).role → "time"
ds.Dimension( "country" ).role → "geo"

var yearrole = ds.Dimension( "year" ).role;
var countryrole = ds.Dimension( "country" ).role;
var timedims = ds.role.time;
var geodims = ds.role.geo;
Likewise, you can ask the other way around.
Get dimensions with role time and role geo.
ds.role.time → ["year"]
ds.role.geo → ["country"]

var sexlabel2 = sex.Category( 2 ).label;
var sexunit2 = sex.Category( 2 ).unit;
var sexcoord2 = sex.Category( 2 ).coordinates;
Get information about a particular sex category.
By index.
sex.Category( 2 ).label → "female"
.unit, .coordinates (only if role metric / geo) → null

var sexlabel2 = sex.Category( "F" ).label;
var sexunit2 = sex.Category( "F" ).unit;
var sexcoord2 = sex.Category( "F" ).coordinates;
Get information about a particular sex category.
By ID.
sex.Category( "F" ).label → "female"
.unit, .coordinates (only if role metric / geo) → null

var dimarray = ds.Dimension( );
var sexarray = sex.Category( );
All methods can be called without arguments.
They will return an array of results.

var malelabel = ds
.Dimension( )[4]
.Category( )[1]
.label;
Use responsibly!
Always minimize calling methods
without arguments.
// sex (5th dimension)
// male (2nd category)

var malelabel = ds
.Dimension( 4 )
.Category( 1 )
.label;
Simpler.
Still, you should minimize calling
the same method with the same argument
several times.

var malelabel =
sex
.Category( 1 )
.label;
If you must, store the result in a variable.

the
JSON-stat
Javascript
Toolkit
It offers methods
to easily traverse
the JSON-stat
tree:
Dataset
Dimension
Category
Data

var cell44 = ds.Data( 44 ).value;
var cell44 = ds.Data( [0,0,7,0,2] ).value;
Get the value in cell 44.
By value index and by dimensions’ indexes.
ds.Data( 44 ).value → 1202.8
ds.Data( [0,0,7,0,2] ).value → 1202.8

var cell44 = ds.Data( {
country: "CA",
year : "2012",
concept : "POP",
age: "34",
sex: "F"
} ).value;
Get the value in cell 44.
By dimension/category ID.
ds.Data( {…} ).value → 1202.8

country: "CA",
year : "2012",
concept : "POP",
age: "34",
sex: "F"
} ).value;
Single category dimensions are not required.
ds.Data( {…} ).value → 1202.8

var cell44 = ds.Data( 44 ).status;
var cell44 = ds.Data( [0,0,7,0,2] ).status;
country: "CA",
year : "2012",
concept : "POP",
age: "34",
sex: "F"
} ).status;
Get cell status, if available.
ds.Data( {…} ).status → "a"

var pop34 = ds.Data( {
country: "CA",
year : "2012",
concept : "POP",
age: "34",
sex: "F"
} );
By removing one (and only one) required
dimension, you get an array of results (slice).
(In the example, population of age 30-34
by sex in Canada in 2012.)

var data = ds.Data( );
Get an array with information for every cell.
(“Information” currently means value and status.)

var data = ds.Data( );
// It allows you to rebuild the value array like this:
var value = ds.Data( ).map(
function( e ){
return e.value;
}
);
// But you can directly access the original value and status
// like this:
var value = ds.value;
var status = ds.status;

J.Dataset( )
.Dimension( )
.Category( )
.Data( )
Chainable traversing methods
J.Dataset( )
.toTable( )
Chainable transformation methods

J.Dataset( )
.Dimension( )
.Category( )
.Data( )
Chainable traversing methods
J.Dataset( )
.toTable( )
Get sections of the dataset.
Get data and main metadata
in tabular form.

J.Dataset( )
.toTable( )
Get data and main metadata
in tabular form.
Useful to export the dataset content
to other table-based structures

var tbl = ds.toTable( { type : "arrobj" } );
[
{
age : "Total",
concept : "Persons (thousands)",
country : "Canada",
sex : "Total",
value : 34880.5,
year : "2012"
},
{
age : "Total",
country : "Canada",
sex : "Male",
value : 17309.1,
year : "2012"
},
…
]
Get an array of objects describing every cell.

var tbl = ds.toTable( { type : "arrobj", status : true } );
[
{
age : "Total",
country : "Canada",
sex : "Total",
value : 34880.5, status : "a",
year : "2012"
},
{
age : "Total",
country : "Canada",
sex : "Male",
value : 17309.1, status : "a",
year : "2012"
},
…
]
It can include status information.

var tbl = ds.toTable( { type : "arrobj", content : "id" } );
[
{
age : "T",
concept : "POP",
country : "CA",
sex : "T",
value : 34880.5,
year : "2012"
},
{
age : "T",
concept : "POP",
country : "CA",
sex : "M",
value : 17309.1,
year : "2012"
},
…
]
It can use categories’ IDs instead of labels.

var tbl = ds.toTable(
{
type : "arrobj",
content : "id",
function ( d, i ){
if ( d.sex === "F" && d.concept === "POP" ){
return { age : d.age, population : d.value*1000 };
}
}
}
);
// Get only slice females, persons (in thousands), transform
// thousands into persons and keep age and population only.
It can be post-processed with a callback function.

var tbl = ds.toTable( { type : "object" } );
{
cols : [
{
id : "country",
label : "Country",
type : "string",
},
{
id : "year",
label : "Year",
type : "string",
},
...
],
rows : [
...
]
}
Get an object of arrays (Google DataTable format).

var tbl = ds.toTable( { type : "array" } );
[
[
"Country",
"Year",
"Age group",
"Population and %",
"Sex",
"Value"
],
[
"Canada",
"2012",
"Total",
"Persons (thousands)",
"Total",
34880.5
],
...
]
Get an array of arrays (CSV-like format).

These are just
the main features of
the
JSON-stat
Javascript
Toolkit
json-stat.com

JJT is also available
on the server as
a Node.js module.
npm install jsonstat
https://www.npmjs.com/package/jsonstat

Built on top of JJT
the
JSON-stat
Javascript
Utilities
Suite

Built on top of JJT
the
JSON-stat
Javascript
Utilities
Suite
High level utilities
tbrowser: interactive,
pivotal table
datalist: unidimensional
table
fromTable: import from
JSON tabular formats
fromCSV/toCSV:
import/export from/to
CSV

all pictures from
Blocks picture in slide 1: Soma, by Dru! (CC BY-NC)
Atomium in slide 2: Fighting Gravity –
Atomium, Brussels, by Jan Faborsky
(CC BY-NC-ND)
Sculture in slide 3: Cubes, by Alex
[Fino] LA (CC BY-SA)
Egg in slide 50: Egg, by Auntie P
(CC BY-NC-SA)

JSON-stat & JS: the JSON-stat Javascript Toolkit

More Related Content

What's hot (14)

Similar to JSON-stat & JS: the JSON-stat Javascript Toolkit (20)

More from Xavier Badosa (20)

Recently uploaded (20)

JSON-stat & JS: the JSON-stat Javascript Toolkit