incrcovmat

Compute an unbiased sample covariance matrix incrementally.

A covariance matrix is an M-by-M matrix whose elements specified by indices j and k are the covariances between the jth and kth data variables. For unknown population means, the unbiased sample covariance is defined as

normal c normal o normal v Subscript normal j normal k normal n Baseline equals StartFraction 1 Over n minus 1 EndFraction sigma-summation Underscript i equals 0 Overscript n minus 1 Endscripts left-parenthesis x Subscript i j Baseline minus x overbar Subscript j n Baseline right-parenthesis left-parenthesis x Subscript i k Baseline minus x overbar Subscript k n Baseline right-parenthesis

For known population means, the unbiased sample covariance is defined as

normal c normal o normal v Subscript normal j normal k normal n Baseline equals StartFraction 1 Over n EndFraction sigma-summation Underscript i equals 0 Overscript n minus 1 Endscripts left-parenthesis x Subscript i j Baseline minus mu Subscript j Baseline right-parenthesis left-parenthesis x Subscript i k Baseline minus mu Subscript k Baseline right-parenthesis

Usage

var incrcovmat = require( '@stdlib/stats/incr/covmat' );

incrcovmat( out[, means] )

Returns an accumulator function which incrementally computes an unbiased sample covariance matrix.

// Create an accumulator for computing a 2-dimensional covariance matrix:
var accumulator = incrcovmat( 2 );

The out argument may be either the order of the covariance matrix or a square 2-dimensional ndarray for storing the unbiased sample covariance matrix.

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

var buffer = new Float64Array( 4 );
var shape = [ 2, 2 ];
var strides = [ 2, 1 ];

// Create a 2-dimensional output covariance matrix:
var cov = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' );

var accumulator = incrcovmat( cov );

When means are known, the function supports providing a 1-dimensional ndarray containing mean values.

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

var buffer = new Float64Array( 2 );
var shape = [ 2 ];
var strides = [ 1 ];

var means = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' );

means.set( 0, 3.0 );
means.set( 1, -5.5 );

var accumulator = incrcovmat( 2, means );

accumulator( [vector] )

If provided a data vector, the accumulator function returns an updated unbiased sample covariance matrix. If not provided a data vector, the accumulator function returns the current unbiased sample covariance matrix.

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

var buffer = new Float64Array( 4 );
var shape = [ 2, 2 ];
var strides = [ 2, 1 ];
var cov = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' );

buffer = new Float64Array( 2 );
shape = [ 2 ];
strides = [ 1 ];
var vec = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' );

var accumulator = incrcovmat( cov );

vec.set( 0, 2.0 );
vec.set( 1, 1.0 );

var out = accumulator( vec );
// returns <ndarray>

var bool = ( out === cov );
// returns true

vec.set( 0, 1.0 );
vec.set( 1, -5.0 );

out = accumulator( vec );
// returns <ndarray>

vec.set( 0, 3.0 );
vec.set( 1, 3.14 );

out = accumulator( vec );
// returns <ndarray>

out = accumulator();
// returns <ndarray>

Examples

var randu = require( '@stdlib/random/base/randu' );
var ndarray = require( '@stdlib/ndarray/ctor' );
var Float64Array = require( '@stdlib/array/float64' );
var incrcovmat = require( '@stdlib/stats/incr/covmat' );

var cov;
var cxy;
var cyx;
var vx;
var vy;
var i;

// Initialize an accumulator for a 2-dimensional covariance matrix:
var accumulator = incrcovmat( 2 );

// Create a 1-dimensional data vector:
var buffer = new Float64Array( 2 );
var shape = [ 2 ];
var strides = [ 1 ];

var vec = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' );

// For each simulated data vector, update the unbiased sample covariance matrix...
for ( i = 0; i < 100; i++ ) {
    vec.set( 0, randu()*100.0 );
    vec.set( 1, randu()*100.0 );
    cov = accumulator( vec );

    vx = cov.get( 0, 0 ).toFixed( 4 );
    vy = cov.get( 1, 1 ).toFixed( 4 );
    cxy = cov.get( 0, 1 ).toFixed( 4 );
    cyx = cov.get( 1, 0 ).toFixed( 4 );

    console.log( '[ %d, %d\n  %d, %d ]', vx, cxy, cyx, vy );
}