Skip to content

README.md

Latest commit

 

History

History
247 lines (161 loc) · 8.82 KB

README.md

File metadata and controls

247 lines (161 loc) · 8.82 KB

incrnanmmeanvar

Compute a moving arithmetic mean and unbiased sample variance incrementally, skipping NaN values.

For a window of size W, the arithmetic mean is defined as

$$\bar{x} = \frac{1}{W} \sum_{i=0}^{W-1} x_i$$

and the unbiased sample variance is defined as

$$s^2 = \frac{1}{W-1} \sum_{i=0}^{W-1} ( x_i - \bar{x} )^2$$

Usage

var incrnanmmeanvar = require( '@stdlib/stats/incr/nanmmeanvar' );

incrnanmmeanvar( [out,] window )

Returns an accumulator function which incrementally computes a moving arithmetic mean and unbiased sample variance while skipping NaN values. The window parameter defines the maximum number of most recent non-NaN values used to compute the moving statistics.

var accumulator = incrnanmmeanvar( 3 );

By default, the returned accumulator function returns the accumulated values as a two-element array. To avoid unnecessary memory allocation, the function supports providing an output (destination) object. Unlike incrmmeanvar, this accumulator ignores (skips) any NaN values and does not allow them to propagate into the moving mean and variance.

var Float64Array = require( '@stdlib/array/float64' );

var accumulator = incrnanmmeanvar( new Float64Array( 2 ), 3 );

accumulator( [x] )

If provided an input value x, the accumulator function updates and returns the current moving arithmetic mean and unbiased sample variance. If x is NaN, the value is ignored (i.e., it does not affect the window). If not provided an input value x, the accumulator function returns the current accumulated values without updating.

var incrnanmmeanvar = require( '@stdlib/stats/incr/nanmmeanvar' );

var accumulator = incrnanmmeanvar( 3 );

var out = accumulator();
// returns null

// Fill the window (no NaNs yet)...
out = accumulator( 2.0 ); // [2.0]
// returns [ 2.0, 0.0 ]

out = accumulator( NaN ); // NaN is ignored [2.0]
// returns [ 2.0, 0.0 ]

out = accumulator( 1.0 ); // [2.0, 1.0]
// returns [ 1.5, 0.5 ]

out = accumulator( 3.0 ); // [2.0, 1.0, 3.0]
// returns [ 2.0, 1.0 ]

// Window begins sliding...
out = accumulator( -7.0 ); // [1.0, 3.0, -7.0]
// returns [ -1.0, 28.0 ]

out = accumulator( NaN );  // NaN ignored [1.0, 3.0, -7.0]
// returns [ -1.0, 28.0 ]

out = accumulator( -5.0 ); // [3.0, -7.0, -5.0]
// returns [ -3.0, 28.0 ]

out = accumulator();
// returns [ -3.0, 28.0 ]

Notes

  • Input values are not type checked. If provided NaN, the value is ignored and does not affect the moving window or the accumulated statistics. If non-numeric inputs are possible, you are advised to type check and handle them before passing values to the accumulator function.
  • As W valid (non-NaN) values are needed to fill the window buffer, the first W-1 returned values are calculated from smaller sample sizes. Until the window has received W valid values, each returned value is calculated from all valid inputs seen so far.

Examples

var randu = require( '@stdlib/random/base/randu' );
var Float64Array = require( '@stdlib/array/float64' );
var ArrayBuffer = require( '@stdlib/array/buffer' );
var incrnanmmeanvar = require( '@stdlib/stats/incr/nanmmeanvar' );

var offset;
var acc;
var buf;
var out;
var mv;
var N;
var v;
var i;
var j;

// Define the number of accumulators:
N = 5;

// Create an array buffer for storing accumulator output:
buf = new ArrayBuffer( N*2*8 );

// Initialize accumulators:
acc = [];
for ( i = 0; i < N; i++ ) {
    // Compute the byte offset for the i­th accumulator:
    offset = i * 2 * 8;

    // Create a typed array view over the correct section of the buffer:
    out = new Float64Array( buf, offset, 2 );

    // Create a moving mean/variance accumulator with window W = 5:
    acc.push( incrnanmmeanvar( out, 5 ) );
}

// Simulate streaming data updates:
for ( i = 0; i < 100; i++ ) {
    for ( j = 0; j < N; j++ ) {

        // Generate random values, but occasionally insert NaN.
        // Any NaNs are ignored by the accumulator.
        v = ( randu() > 0.1 ) ? randu() * 100 : NaN;

        // Update accumulator j:
        acc[ j ]( v );
    }
}

// Display final moving means and variances:
console.log( 'Mean\tVariance' );
for ( i = 0; i < N; i++ ) {
    mv = acc[ i ](); // Get the current result
    console.log( mv[ 0 ].toFixed( 3 ) + '\t' + mv[ 1 ].toFixed( 3 ) );
}

See Also