downsample

downsample

Downsampling methods for time series visualisation.

Installation | Usage | API | Demo | Acknowledgement

downsample is useful when, not extremely surprisingly, you need to downsample a numeric time series before visualizing it without losing the visual characteristics of the data.

Installation

downsample is an NPM module. You can easily download it by typing something like the following in your project:

# for all the npm people out there
npm install downsample

# or if you are a fan of yarn
yarn add downsample

Usage

The package exports several methods for data downsampling:

• ASAP Automatic Smoothing for Attention Prioritization read more here
• SMA Simple moving average read more here
• LTTB Largest triangle three buckets read more here
• LTOB Largest triangle one bucket read more here
• LTD Largest triangle dynamic read more here

You can read more about the details of these in the API section below.

API

ASAP :boom: new in 1.2.0 :boom:

Automatic Smoothing for Attention Prioritization (read more here) is a smoothing rather than downsampling method - it will remove the short-term noise and reveal the large-scale deviations.

ASAP accepts an array of data points (see DataPoint) or a TypedArray (see TypedArray support) and a target resolution (number of output data points) as arguments. It will always return the points in XYDataPoint format. See advanced API if you need to work with a custom data type.

function ASAP(data: DataPoint[], targetResolution: number): XYDataPoint[]

import { ASAP } from 'downsample';

// Or if your codebase does not supprot tree-shaking
import { ASAP } from 'downsample/methods/ASAP';

const chartWidth = 1000;
const smooth = ASAP([
  [0, 1000],
  [1, 1243],
  // ...
], chartWidth);

SMA :boom: new in 1.2.0 :boom:

Simple moving average with variable slide (read more here).

SMA accepts an array of data points (see DataPoint) or a TypedArray (see TypedArray support), size of a window over which to calculate average and a slide - an amount by which the window is shifted. It will always return the points in XYDataPoint format. See advanced API if you need to work with a custom data type.

function SMA(data: DataPoint[], windowSize: number, slide?: number = 1): XYDataPoint[]

import { SMA } from 'downsample';

// Or if your codebase does not supprot tree-shaking
import { SMA } from 'downsample/methods/SMA';

const chartWidth = 1000;
const smooth = SMA([
  [0, 1000],
  [1, 1243],
  // ...
], chartWidth);

LTTB

Largest triangle three buckets (read more here). If you are looking for the best performing downsampling method then look no more!

function LTTB(data: DataPoint[], targetResolution: number): DataPoint[]

LTTB accepts an array of data points (see DataPoint) or a TypedArray (see TypedArray support) and a target resolution (number of output data points) as arguments. See advanced API if you need to work with a custom data type.

The format of the data will be preserved, i.e. if passing an array of [number, number] data points as data, you will get an array of [number, number] on the output.

import { LTTB } from 'downsample';

// Or if your codebase does not supprot tree-shaking
import { LTTB } from 'downsample/methods/LTTB';

const chartWidth = 1000;
const downsampled = LTTB([
  [0, 1000],
  [1, 1243],
  // ...
], chartWidth);

LTOB

Largest triangle one bucket (read more here). Performs only slightly worse than LTTB.

function LTOB(data: DataPoint[], targetResolution: number): DataPoint[]

LTOB accepts an array of data points (see DataPoint) or a TypedArray (see TypedArray support) and a target resolution (number of output data points) as arguments. See advanced API if you need to work with a custom data type.

The format of the data will be preserved, i.e. if passing an array of [number, number] data points as data, you will get an array of [number, number] on the output.

import { LTOB } from 'downsample';

// Or if your codebase does not supprot tree-shaking
import { LTOB } from 'downsample/methods/LTOB';

const chartWidth = 1000;
const downsampled = LTOB([
  [0, 1000],
  [1, 1243],
  // ...
], chartWidth);

LTD

Largest triangle dynamic (read more here). The simplest downsampling method.

function LTD(data: DataPoint[], targetResolution: number): DataPoint[]

LTD accepts an array of data points (see DataPoint) or a TypedArray (see TypedArray support) and a target resolution (number of output data points) as arguments. See advanced API if you need to work with a custom data type.

The format of the data will be preserved, i.e. if passing an array of [number, number] data points as data, you will get an array of [number, number] on the output.

import { LTD } from 'downsample';

// Or if your codebase does not supprot tree-shaking
import { LTD } from 'downsample/methods/LTD';

const chartWidth = 1000;
const downsampled = LTD([
  [0, 1000],
  [1, 1243],
  // ...
], chartWidth);

DataPoint type

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

type DataPoint =
  [number, number] |
  [Date, number] |
  { x: number; y: number } |
  { x: Date; y: number } |

TypedArray support

It is now possible to pass TypedArray data to downsampling functions. The returned type will then match the input type, e.g. if Int16Array is passed in, the result will be a Int16Array:

const input: Int16Array = new Int16Array(...);
const result: Int16Array = LTD(input, 1000);

Advanced API

All the functions above work with DataPoint objects as a reasonable default. If however this does not fit your needs you can create your own version of a function using a downsampling function factory.

createASAP

Creates an ASAP smoothing function for a specific point data type P.

function createASAP({
  x: string | number | (point: P) => number,
  y: string | number | (point: P) => number,
  toPoint: (x: number, y: number) => P
}): ASAP;

createSMA

Creates a SMA smoothing function for a specific point data type P.

function createSMA({
  x: string | number | (point: P) => number,
  y: string | number | (point: P) => number,
  toPoint: (x: number, y: number) => P
}): SMA;

createLTD

Creates an LTD downsampling function for a specific point data type P.

function createLTD({
  x: string | number | (point: P) => number,
  y: string | number | (point: P) => number
}): LTD;

createLTOB

Creates an LTOB downsampling function for a specific point data type P.

function createLTOB({
  x: string | number | (point: P) => number,
  y: string | number | (point: P) => number
}): LTOB;

createLTTB

Creates an LTTB downsampling function for a specific point data type P.

function createLTTB({
  x: string | number | (point: P) => number,
  y: string | number | (point: P) => number
}): LTTB;

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.

Acknowledgement

The implementation of LTD, LTOB and LTTB is based on Sveinn Steinarsson's 2013 paper Downsampling Time Series for Visual Representation that can be found here.

The implementation of ASAP is based on Kexin Rong's and Peter Bailis's 2017 paper. ASAP: Prioritizing Attention via Time Series Smoothing that can be found here. The original code can be found here