downsample

Collection of several downsampling methods for time series visualisation purposes.

Demo

There is a very minimal interactive demo app available if you want to play around with the results of downsampling. Check it out here.

Installation

downsample is an NPM module. Install using

  npm install downsample

Acknowledgement

The implementation is based on Sveinn Steinarsson's 2013 paper Downsampling Time Series for Visual Representation that can be found here.

Usage

Three downsampling methods are currently supported, description of all three can be found here:

Largest triangle three buckets (LTTB)
Largest triangle one bucket (LTOB)
Largest triangle dynamic (LTD)

Downsampling a series of data points using either of these looks like this:

// ES6
import { LTD, LTOB, LTTB } from "downsample";

// Or old school
var LTD = require("downsample").LTD;
var LTOB = require("downsample").LTOB;
var LTTB = require("downsample").LTTB;

// The number of target data points, 100 for example
const numPointsInDownsampledData: number = 100;

// See the API docs for supported input data formats
const data: DataPoint[] = [ ... ];
const downsampledDataLTOB: DataPoint[] = LTOB(data, numPointsInDownsampledData);

// downsampledDataLTOB now contains data downsampled to contain 
// no more than numPointsInDownsampledData data points.
//
// the output data format matches the input one and data points are copied
// shallowly to the resulting array

API

DataPoint type

Represents a data point in the input data array. Two formats are currently supported:

TupleDataPoint is an array tuple of a number or a Date representing the independent variable (e.g. time) and a number representing the value:

const numericTupleDataPoint: TupleDataPoint = [1, 152.2];

const dateTupleDataPoint: TupleDataPoint = [new Date(), 45.1];

XYDataPoint is an object hash with x property representing the independent variable (e.g. time) and an y property the value:

const numericXYDataPoint: XYDataPoint = { x: 1, y: 152.2 };

const dateXYDataPoint: XYDataPoint = { x: new Date(), y: 152.2 };

downsample.LTOB<T extends DataPoint>(data: T[], desiredLength: number): T[]

Implementation of Largest triangle one bucket downsampling method.

data: DataPoint[] is the input array. This array should be sorted by the independent variable otherwise the results will be unpredictable.

desiredLength: number is the length of the downsampled array.

This function will throw an error if the desiredLength is negative.

downsample.LTTB<T extends DataPoint>(data: T[], desiredLength: number): T[]

Implementation of Largest triangle three buckets downsampling method.

data: DataPoint[] is the input array. This array should be sorted by the independent variable otherwise the results will be unpredictable.

desiredLength: number is the length of the downsampled array.

This function will throw an error if the desiredLength is negative.

downsample.LTD<T extends DataPoint>(data: T[], desiredLength: number): T[]

Implementation of Largest triangle dynamic downsampling method. Especially good for unevenly sampled data, for evenly spaced data LTTB should produce better results.

data: DataPoint[] is the input array. This array should be sorted by the independent variable otherwise the results will be unpredictable.

desiredLength: number is the length of the downsampled array.

This function will throw an error if the desiredLength is negative.