stats-incremental

stats-incremental

A light statstical package for incremental (i.e. rolling, streaming) sets of numbers.

E.g. given a source of numbers of unknown length that you would like to at any given time know any of:

• count
• min
• max
• sum
• variance
• standard_deviation
• simple moving average

This module can be used either with Node streams via a wrapper such as through2 or without being streaming.

Example

Non-streaming:

var Stats = require("stats-incremental")

var dice = require("dice")
var s = Stats()

var rolls = []
for (var i = 0; i < 100; i++) {
  s.update(dice.sum(dice.roll("2d6")))
  console.log(s.getAll())
}

/* E.g.
  { n: 97,
  min: 2,
  max: 12,
  sum: 673,
  mean: 6.938144329896907,
  variance: 5.851843979168881,
  standard_deviation: 2.419058490233107,
  sma50: 6.82 }
*/


console.log(s.mean)
console.log(s.standard_deviation)

With streams:

var spigot = require("stream-spigot")
var through2 = require("through2")
var terminus = require("terminus")

var Stats = require("stats-incremental")
var s = Stats()

var statStream = through2.obj(function (chunk, encoding, callback) {
  s.update(chunk)
  if (s.n % 100000 === 0) {
    console.log(s.getAll())
  }
  this.push(chunk)
  callback()
})

spigot.sync({objectMode: true}, Math.random)
  .pipe(statStream)
  .pipe(terminus.devnull({objectMode: true}))

/*
  { n: 100000,
    min: 2.0884908735752106e-7,
    max: 0.9999937505926937,
    sum: 49861.06196602131,
    mean: 0.49861061966021336,
    variance: 0.08331362954827709,
    standard_deviation: 0.28864100462040576,
    sma50: 0.5422519558777934 }
  { n: 200000,
    min: 2.0884908735752106e-7,
    max: 0.9999937505926937,
    sum: 99904.73041411326,
    mean: 0.49952365207056687,
    variance: 0.08316120223669865,
    standard_deviation: 0.2883768406732736,
    sma50: 0.4396136475716979 }
*/

API

const Stats = require("stats-incremental")

var stats = new Stats(smaBins)

Create a new incremental stats aggregator. The smaBins argument is optional (default 50) and will choose the size of recent window to retain to calculate the Simple Moving Average on the recent data.

stats.update(value)

Update the aggregator with a value. Converted to a Number via parseFloat. If this results in NaN the update is skipped.

stats.getAll()

Get a up-to-date clone of all of the stats stored.

E.g.

{ n: 97,
  min: 2,
  max: 12,
  sum: 673,
  mean: 6.938144329896907,
  variance: 5.851843979168881,
  standard_deviation: 2.419058490233107,
  sma50: 6.82 }

stats.n

The count of observations.

stats.min

The min value observed.

stats.max

The max value observed.

stats.sum

The sum of all values observed.

stats.mean

The arithmetic mean of the observations.

stats.variance

The variance from the mean.

stats.standard_deviation

The standard deviation of the values from the mean.

stats.smaXX

Get the Simple Moving Average of the recent data. Default is to store 50 recent records and expose an sma50 property with the simple moving average. If the Stats object is created with an argument of a number of SMA bins, the property will reflect the number of bins, e.g. Stats(100) will have an sma100 instead of sma50 property.

Alternatives

stats-lite Operates on complete sets of numbers.

stream-statistics Is a similar module dedicated to streams.

LICENSE

MIT