slayer

JavaScript time series spike detection for Node.js; like the Octave findpeaks function.

Slayer

JavaScript time series spike detection for Node.js; like the Octave findpeaks function.

Time series are often displayed as bar, line or area charts. A peak or spike in a time series is a the highest value before the trend start to decrease.

In reality you do not need all the spikes. You only need the highest spike amongst them. Slayer helps to identify these local peaks easily.

Install

npm bower old school
npm install --save slayer - download zip file

Usage

Slayer exposes a fluent JavaScript API and requires as little configuration as possible. The following examples illustrates common use cases.

var slayer = require('slayer');
var arrayData = [0, 0, 0, 12, 0, …];
 
slayer().fromArray(arrayData, function(errspikes){
  console.log(spikes);      // [ { x: 4, y: 12 }, { x: 12, y: 25 } ] 
});
var slayer = require('slayer');
var arrayData = [, { date: '', value: 12 }, …];
 
slayer()
  .y(function(item){ return item.value; })
  .fromArray(arrayData, function(errspikes){
    console.log(spikes);    // [ { x: 4, y: 12 }, { x: 12, y: 25 } ] 
  });

Not yet implemented.

var slayer = slayer().pipe(process.stdin);
 
slayer.on('peak', function onSpike(spike){
  console.log(spike);      // { x: 4, y: 12 } 
});
 
slayer.on('end', function(){
  console.log('Processing done!');
});

API

Access the Slayer API by requiring the CommonJS module:

var slayer = require('slayer');

A spike object is an object composed of two keys:

  • x: the index value within the time series array;
  • y: the spike value within the time series array.

The slayer() factory returns a new chainable instance of Slayer.

The optional config object enables you to adjust its behaviour according to your needs:

  • minPeakDistance (Integer): size of the values overlooked window. _Default is 30_;
  • minPeakHeight (Number): discard any value below that threshold. _Default is 0_.

Returns a slayer chainable object.

Data accessor applied to each series item and used to determine spike values.

It will return this value as the y value of a spike object.

slayer()
  .y(function(item){
    return item.value;     // considering item looks like `{ value: 12 }` 
  })
  .fromArray(arrayData, function(errspikes){
    console.log(spikes);   // { x: 4, y: 12 } 
  });

Returns a mutated slayer chainable object.

Index accessor applied to each series item.

It will return this value as the x value of a spike object.

slayer()
  .x(function(itemi){
    return item.date;      // considering item looks like `{ date: '2014-04-12T17:31:40.000Z', value: 12 }` 
  })
  .fromArray(arrayData, function(errspikes){
    console.log(spikes);   // { x: '2014-04-12T17:31:40.000Z', y: 12 } 
  });

Returns a mutated slayer chainable object.

Transforms the spike object before returning it as part of the found spike collections.

It is useful if you want to add extra data to the returned spike object.

slayer()
  .transform(function(xyItemoriginalItemi){
    xyItem.id = originalItem.id;
 
    return xyItem;
  })
  .fromArray(arrayData, function(errspikes){
    console.log(spikes);   // { x: 4, y: 12, id: '21232f297a57a5a743894a0e4a801fc3' } 
  });

Returns a mutated slayer chainable object.

Processes an array of data and calls an onComplete callback with an error and spikes parameters.

slayer()
  .fromArray(arrayData, function(errspikes){
    if (err){
      console.error(err);
      return;
    }
 
    console.log(spikes);   // { x: 4, y: 12, id: '21232f297a57a5a743894a0e4a801fc3' } 
  });

Returns undefined.

Contributing and testing

If you wish to contribute the project with code but you fear to break something, no worries as TravisCI takes care of this for each Pull Request.

Nobody will blame your code. And feel free to ask before making a pull request. We will try to provide you guidance for code design etc.

If you want to run the tests locally, simply run:

npm test

Licence

Copyright 2014 British Broadcasting Corporation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.