Skip to content

steelbreeze/pivot

Repository files navigation

pivot

Maintainability

A minimalist pivot table library for TypeScript/JavaScript. While small (a mere 485 bytes when minified), this library is large in capability, supporting derived and custom dimensions, derived fields for dimensions and calculations, composite dimensions, filtering.

The library also provides a modest set of numerical selectors. Suggestions for additions, or better still contributions, are welcome.

Why create another pivot table library?

There are plenty of pivot table libraries in existence, so why create another one? Well, this is a spin-off from the steelbreeze/landscape project, where instead of aggregating numerical data from the pivot cube, non-numerical data is needed.

It also focuses just on dimension and cube creation, without any layout considerations keeping it small and unopinionated.

n-cubes

The libary allows 1-n dimensions to be passed into the pivot function allowing n-cube (or hypercube) generation.

Installation

NPM

For installation via the node package manager:

npm i @steelbreeze/pivot

Web

For web via a CDN:

import * as pivot from 'https://cdn.skypack.dev/@steelbreeze/pivot';

Documentation

The documentation can be found here, and more discussion in the Wiki.

Example

The following is the result of pivoting publicly available information about the Fulham Football Club men's squad at the end of the 2020/21 season, calculating the average age of players by position and country.

import { distinct, criteria, pivot, map, average } from '@steelbreeze/pivot';
import { squad } from './fulham';

// the position dimension we want in a custom order
const positions = ['Goalkeeper', 'Defender', 'Midfielder', 'Forward'];

// the countries dimension we derive from the data and order alphabetically
const countries = squad.map(player => player.country).filter(distinct).sort();

// we then create dimensions which also reference a property in the source data 
const x = positions.map(criteria('position'));
const y = countries.map(criteria('country'));

// create the pivot cube from the squad data using position and country for x and y axes
let cube = pivot(squad, y, x);

// find the average age of players by position by country as at 2021-05-23
const result = map(cube, average(age(new Date('2021-05-23'))));

The full example can be found here.

The selection is the average age of the players grouped by position and country:

        Goalke… Defend… Midfie… Forward
Belgium         32
Camero…                 25
Denmark         24
England         25      23.25   23
France  28      27
Gabon                   27
Jamaica         28              28
Nether…         25
Nigeria         24              22
Portug…                         27
Scotla…                 31
Serbia                          26
Slovak… 24
Spain   33
USA             28

The full example code can be found here.

Alternatively, as can be seen in the web example, non-numerical content can also be queried, mapping the source data to an arbitrary selection:

const result = pivot.map(cube, pivot.select(player => `${player.givenName} ${player.familyName}`));

Resulting in this sort of output:

Goalkeeper Defender Midfielder Forward
Belgium Denis Odoi
Cameroon Andre-Frank Zambo Anguissa
Denmark Joachim Anderson
England Tosin Abarabioyo, Joe Bryan Ruben Loftus-Cheek, Harrison Reed, Josh Onomah, Fabio Carvalho Ademola Lookman
France Alphonse Areola Terence Kongolo
Gabon Mario Lemina
Jamaica Michael Hector Bobby De Cordova-Reid
Netherlands Kenny Tete
Nigeria Ola Aina Josh Maja
Portugal Ivan Cavaleiro
Scotland Kevin McDonald, Tom Cairney
Serbia Aleksander Mitrovic
Slovakia Marek Rodak
Spain Fabrico Agosto Ramirez
USA Tim Ream, Antonee Robinson

Data and calculations correct as of: 2021-05-23.