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.

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

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.

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) and a target resolution (number of output data points) as arguments.

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

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);

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

SMA accepts an array of data points (see DataPoint), size of a window over which to calculate average and a slide - an amount by which the window is shifted.

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

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);

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

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

LTTB accepts an array of data points (see DataPoint) and a target resolution (number of output data points) as arguments.

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);

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) and a target resolution (number of output data points) as arguments.

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);

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) and a target resolution (number of output data points) as arguments.

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);

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 } |

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

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