Time Series Collection

A tiny, blazing fast, time series collection with zero dependencies! (did I get that right?)

This library uses unix timestamps (the number of seconds since the epoch)

Getting Started

import { TimeSeriesCollection } from 'time-series-collection';

// instantiate a new collection
const collection = new TimeSeriesCollection<number>();

// you put some samples in
collection.addSample(unixTime, 50);
collection.addSample(anotherUnixTime, 100);
collection.addSample(aDifferentUnixTime, 150);

// and you get some samples out
collection.getValue(anotherUnixTime);  // 100

Interpolation Algorithms

An interpolator function is used to produce a value when there's no exact match. A few interpolator functions are provided, but you can write your own too!

import { TimeSeriesCollection, closestSample } from 'time-series-collection';

// create a simple interpolator
const interpolatorFn = closestSample();

// instantiate a collection with the interpolator
const collection = new TimeSeriesCollection<number>(interpolatorFn);

// add some samples
collection.addSample(100, 17);
collection.addSample(200, 23);

// always retrieve the closest sample
collection.getValue(0);  // 17
collection.getValue(105);  // 17
collection.getValue(2403);  // 23

Functional API

All the methods of the class are also exposed as functions (although currently these functions do mutate the collection for memory efficiency and performance)

import { TimeSeriesCollectionInterface, addSample, removeTimeFrame } from 'time-series-collection';

// create a collection data structure
const collection: TimeSeriesCollectionInterface<number> = {
    timestamps: [],
    datums: []
};

// add some samples
addSample(collection, unixTime, 42);
addSample(collection, anotherUnixTime, 38);

// retrieve a value
getValue(collection, unixTime);  // 42

Documentation

Class TimeSeriesCollection

constructor<T>(interpolator)

Creates a new instance of a TimeSeriesCollection

Parameter	Type	Description
interpolator	Interpolator	The interpolator to use when getting a value

addSample(timestamp, data)

Adds a sample to the collection

Parameter	Type	Description
timestamp	number	The unix timestamp for this sample
data	T	The data for this sample

addSamples(timestamps, datums)

Adds a list of samples to the collection. The samples do not have to be sorted, but if they are sorted, they will be inserted much faster.

Parameter	Type	Description
timestamps	Array<number>	The list of timestamps to insert
datums	Array<T>	The matching order list of datums to insert

removeTimeFrame(fromTimestampInclusive, toTimestampInclusive, keepClosestSamples)

Removes all samples inside the specified time frame

Parameter	Type	Description
fromTimestampInclusive	number	removes all samples after or at this unix time
toTimestampInclusive	number	removes all samples before or at this unix time
keepClosestSamples	boolean	whether to keep a single sample of either side of the time frames to remove.

removeOutsideTimeFrame(fromTimestampInclusive, toTimestampInclusive, keepClosestSamples)

Removes all samples outside of the specified time frame

Parameter	Type	Description
fromTimestampInclusive	number	removes all samples before or at this unix time
toTimestampInclusive	number	removes all samples after or at this unix time
keepClosestSamples	boolean	whether to keep a single sample of either side of the time frames to remove.

Interpolators

closestSample(maxForwardDistance, maxBackwardsDistance, favourPastSamples)

An interpolator factory function which picks the closest sample, given some constraints

Parameter	Type	Description
maxForwardDistance	number	Ignore samples more than this many seconds before the target timestamp (inclusive)
maxBackwardsDistance	number	Ignore samples more than this many seconds after the target timestamp (inclusive)
favourPastSamples	boolean	Whether to favour past samples of future samples in the case of an exact match

closestFutureSample(maxDistance)

An interpolator factory function which picks the closest sample in the future

Parameter	Type	Description
maxDistance	number	Ignore samples more than this many seconds after the target timestamp (inclusive)

closestPastSample(maxDistance)

An interpolator factory function which picks the closest sample from the past

Parameter	Type	Description
maxDistance	number	Ignore samples more than this many seconds before the target timestamp (inclusive)