A data-prep tool for shaping datasets for visualization with Highcharts.
- NPM: https://www.npmjs.com/package/highseries
- Live Example: https://mbradds.github.io/highseries/
- Source: https://github.com/mbradds/highseries
npm i highseries
The Highcharts JavaScript api requires that the users data conform to a series array of objects, with each series element containing at least a name property, and a data property. The data property is typically a JSON style object of {x:value, y:value} pairs for continuous data, or {name:value, y:value} pairs for categorical data.
Obviously most datasets found online dont conform to this required format. Highseries reads in a users JSON data, as well as several optional parameters for syling/shaping each series, and converts the dataset directly into a js array of valid series objects that Highcharts can work with.
Highseries aims to be dataset structure agnostic, in that the input data can be tidy, non-tidy, and contain any kind of column names, stacking, etc.
import Series from "highseries";
import Highcharts from "highcharts";
const data = [
{ Date: "January 1, 2021", valuesCol1: 100, valuesCol2: 200 },
{ Date: "January 2, 2021", valuesCol1: 200, valuesCol2: 100 },
];
let series = new Series({
data: data,
xCol: "Date",
yCols: ["valuesCol1", "valuesCol2"],
});
//generate the series that will be passed into Highcharts
let forHighcharts = series.hcSeries;
// Generate the chart
Highcharts.chart("container", {
// options - see https://api.highcharts.com/highcharts
series: forHighcharts,
});
These examples go over using Highseries on a real world dataset of monthly NGL exports from Canada.
Period | Product | Origin | Mode of Transportation | Volume (Mb/d) |
---|---|---|---|---|
2015-01-01 | Butane | Canada | Pipeline | 2.57 |
2015-01-01 | Propane | Canada | Pipeline | 12.91 |
... | ... | ... | ... | ... |
import Series from "highseries";
import tidyData from "./tidyData.json";
const colors = {
Marine: "Red",
Pipeline: "Blue",
Railway: "Green",
Truck: "Orange",
};
let tidySeries = new Series({
data: tidyData,
xCol: "Period",
yCols: "Mode of Transportation", //the unique values in this column will have their own series
valuesCol: "Volume (Mb/d)",
filters: { Product: "Propane", Origin: "Canada" },
colors: colors,
});
let forHighcharts = tidySeries.hcSeries;
// Generate the chart
Highcharts.chart("container", {
// options - see https://api.highcharts.com/highcharts
series: forHighcharts,
});
Period | Product | Origin | Marine | Pipeline | Railway | Truck |
---|---|---|---|---|---|---|
2015-01-01 | Butane | Canada | nan | 2.57 | 15.91 | 0.44 |
2015-01-01 | Propane | Canada | nan | 12.91 | 95.28 | 22.71 |
... | ... | ... | ... | ... | ... | ... |
import Series from "highseries";
import nonTidyData from "./nonTidyData.json";
const colors = {
Marine: "Red",
Pipeline: "Blue",
Railway: "Green",
Truck: "Orange",
};
let nonTidySeries = new Series({
data: nonTidyData,
xCol: "Period",
yCols: ["Marine", "Pipeline", "Railway", "Truck"], //these columns will have their own series
filters: { Product: "Propane", Origin: "Canada" },
colors: colors,
});
let forHighcharts = nonTidySeries.hcSeries;
// Generate the chart
Highcharts.chart("container", {
// options - see https://api.highcharts.com/highcharts
series: forHighcharts,
});
The update method can be used to modify the data, keeping some of the original options, such as series colors. This update example converts the chart from Canada Propane exports (Mb/d) to Alberta Butane exports (m3/d).
//continuation from previous non-tidy example
nonTidySeries.update({
data: nonTidyData,
filters: { Product: "Butane", Origin: "Alberta" },
transform: { conv: [159, "*"], decimals: 2 }, //multiply values by 159 to convert Mb/d to m3/d
});
forHighcharts = nonTidySeries.hcSeries;
// Generate the chart
Highcharts.chart("container", {
// options - see https://api.highcharts.com/highcharts
series: forHighcharts,
});
Highseries runs on the client. Here are some tips for optimal performance.
- User data should be sorted beforehand. Highseries has a sort() method, but this should be avoided if possible.
- Non-tidy data usually has a smaller file size compared to the same data in tidy format.
- Only include data columns that are critical for the viz.
- Only include data rows that are critical for the viz. Highseries has a filter parameter, which is useful when paired with a HTML dropdown. Only include data "slices" that will be used in the viz.