# incrpcorrmat

Compute a sample Pearson product-moment correlation matrix incrementally.

A Pearson product-moment correlation matrix is an M-by-M matrix whose elements specified by indices j and k are the Pearson product-moment correlation coefficients between the jth and kth data variables. The Pearson product-moment correlation coefficient between random variables X and Y is defined as

where the numerator is the covariance and the denominator is the product of the respective standard deviations.

For a sample of size n, the sample Pearson product-moment correlation coefficient is defined as

## Usage

var incrpcorrmat = require( '@stdlib/stats/incr/pcorrmat' );


#### incrpcorrmat( out[, means] )

Returns an accumulator function which incrementally computes a sample Pearson product-moment correlation matrix.

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


The out argument may be either the order of the correlation matrix or a square 2-dimensional ndarray for storing the correlation 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 correlation matrix:
var corr = ndarray( 'float64', buffer, shape, strides, 0, 'row-major' );

var accumulator = incrpcorrmat( corr );


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 = incrpcorrmat( 2, means );


#### accumulator( [vector] )

If provided a data vector, the accumulator function returns an updated sample Pearson product-moment correlation matrix. If not provided a data vector, the accumulator function returns the current sample Pearson product-moment correlation 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 corr = 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 = incrpcorrmat( corr );

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

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

var bool = ( out === corr );
// 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 incrpcorrmat = require( '@stdlib/stats/incr/pcorrmat' );

var corr;
var rxy;
var ryx;
var rx;
var ry;
var i;

// Initialize an accumulator for a 2-dimensional correlation matrix:
var accumulator = incrpcorrmat( 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 sample correlation matrix...
for ( i = 0; i < 100; i++ ) {
vec.set( 0, randu()*100.0 );
vec.set( 1, randu()*100.0 );
corr = accumulator( vec );

rx = corr.get( 0, 0 ).toFixed( 4 );
ry = corr.get( 1, 1 ).toFixed( 4 );
rxy = corr.get( 0, 1 ).toFixed( 4 );
ryx = corr.get( 1, 0 ).toFixed( 4 );

console.log( '[ %d, %d\n  %d, %d ]', rx, rxy, ryx, ry );
}