incrpcorrdistmat

Compute a sample Pearson product-moment correlation distance matrix incrementally.

A sample Pearson product-moment correlation distance matrix is an M-by-M matrix whose elements specified by indices j and k are the sample Pearson product-moment correlation distances between the jth and kth data variables. The sample Pearson product-moment correlation distance is defined as

where r is the sample Pearson product-moment correlation coefficient, cov(x,y) is the sample covariance, and σ corresponds to the sample standard deviation. As r resides on the interval [-1,1], d resides on the interval [0,2].

Usage

var incrpcorrdistmat = require( '@stdlib/stats/incr/pcorrdistmat' );

incrpcorrdistmat( out[, means] )

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

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

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

var accumulator = incrpcorrdistmat( dist );

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

accumulator( [vector] )

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

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

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

var bool = ( out === dist );
// 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>

Notes

Due to limitations inherent in representing numeric values using floating-point format (i.e., the inability to represent numeric values with infinite precision), the correlation distance between perfectly correlated random variables may not be 0 or 2. In fact, the correlation distance is not guaranteed to be strictly on the interval [0,2]. Any computed distance should, however, be within floating-point roundoff error.

Examples

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

var dist;
var dxy;
var dyx;
var dx;
var dy;
var i;

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

    dx = dist.get( 0, 0 ).toFixed( 4 );
    dy = dist.get( 1, 1 ).toFixed( 4 );
    dxy = dist.get( 0, 1 ).toFixed( 4 );
    dyx = dist.get( 1, 0 ).toFixed( 4 );

    console.log( '[ %d, %d\n  %d, %d ]', dx, dxy, dyx, dy );
}