Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/DanielLeone/time-series-collection
A tiny, blazing fast, time series collection with zero dependencies! (did I get that right?)
https://github.com/DanielLeone/time-series-collection
Last synced: 2 months ago
JSON representation
A tiny, blazing fast, time series collection with zero dependencies! (did I get that right?)
- Host: GitHub
- URL: https://github.com/DanielLeone/time-series-collection
- Owner: DanielLeone
- License: mit
- Created: 2018-04-02T09:31:27.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-13T22:29:30.000Z (about 2 years ago)
- Last Synced: 2024-03-23T04:01:45.549Z (10 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.46 MB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-blazingly-fast - time-series-collection - A tiny, blazing fast, time series collection with zero dependencies! (did I get that right?) (TypeScript)
README
# Time Series Collection
[](https://badge.fury.io/js/time-series-collection)
[](https://travis-ci.org/DanielLeone/time-series-collection)
[](https://coveralls.io/github/DanielLeone/time-series-collection?branch=master)
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
```typescript
import { TimeSeriesCollection } from 'time-series-collection';
// instantiate a new collection
const collection = new TimeSeriesCollection();
// 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!
```typescript
import { TimeSeriesCollection, closestSample } from 'time-series-collection';
// create a simple interpolator
const interpolatorFn = closestSample();
// instantiate a collection with the interpolator
const collection = new TimeSeriesCollection(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)
```typescript
import { TimeSeriesCollectionInterface, addSample, removeTimeFrame } from 'time-series-collection';
// create a collection data structure
const collection: TimeSeriesCollectionInterface = {
timestamps: [],
datums: []
};
// add some samples
addSample(collection, unixTime, 42);
addSample(collection, anotherUnixTime, 38);
// retrieve a value
getValue(collection, unixTime); // 42
```
## Documentation
### Class `TimeSeriesCollection`
#### `constructor(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` | The list of timestamps to insert
| datums | `Array` | 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) | |