README.md

scovarmtk

Calculate the covariance of two one-dimensional single-precision floating-point ndarrays provided known means and using a one-pass textbook algorithm.

The population covariance of two finite size populations of size N is given by

$$\mathop{\mathrm{cov_N}} = \frac{1}{N} \sum_{i=0}^{N-1} (x_i - \mu_x)(y_i - \mu_y)$$

where the population means are given by

$$\mu_x = \frac{1}{N} \sum_{i=0}^{N-1} x_i$$

and

$$\mu_y = \frac{1}{N} \sum_{i=0}^{N-1} y_i$$

Often in the analysis of data, the true population covariance is not known a priori and must be estimated from samples drawn from population distributions. If one attempts to use the formula for the population covariance, the result is biased and yields a biased sample covariance. To compute an unbiased sample covariance for samples of size n,

$$\mathop{\mathrm{cov_n}} = \frac{1}{n-1} \sum_{i=0}^{n-1} (x_i - \bar{x}_n)(y_i - \bar{y}_n)$$

where sample means are given by

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

and

$$\bar{y} = \frac{1}{n} \sum_{i=0}^{n-1} y_i$$

The use of the term n-1 is commonly referred to as Bessel's correction. Depending on the characteristics of the population distributions, other correction factors (e.g., n-1.5, n+1, etc) can yield better estimators.

Usage

var scovarmtk = require( '@stdlib/stats/base/ndarray/scovarmtk' );

scovarmtk( arrays )

Computes the covariance of two one-dimensional single-precision floating-point ndarrays provided known means and using a one-pass textbook algorithm.

var Float32Array = require( '@stdlib/array/float32' );
var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
var ndarray = require( '@stdlib/ndarray/base/ctor' );

var opts = {
    'dtype': 'float32'
};

var xbuf = new Float32Array( [ 1.0, -2.0, 2.0 ] );
var x = new ndarray( opts.dtype, xbuf, [ 3 ], [ 1 ], 0, 'row-major' );

var ybuf = new Float32Array( [ 2.0, -2.0, 1.0 ] );
var y = new ndarray( opts.dtype, ybuf, [ 3 ], [ 1 ], 0, 'row-major' );

var meanx = scalar2ndarray( 1.0/3.0, opts );
var meany = scalar2ndarray( 1.0/3.0, opts );
var correction = scalar2ndarray( 1.0, opts );

var v = scovarmtk( [ x, y, meanx, meany, correction ] );
// returns ~3.8333

The function has the following parameters:

• arrays: array-like object containing the following ndarrays in order:

  1. first one-dimensional input ndarray.
  2. second one-dimensional input ndarray.
  3. a zero-dimensional ndarray specifying mean of the first one-dimensional ndarray.
  4. a zero-dimensional ndarray specifying mean of the second one-dimensional ndarray.
  5. a zero-dimensional ndarray specifying degrees of freedom adjustment. Setting this parameter to a value other than 0 has the effect of adjusting the divisor during the calculation of the covariance according to N-c where c corresponds to the provided degrees of freedom adjustment. When computing the population covariance, setting this parameter to 0 is the standard choice (i.e., the provided arrays contain data constituting entire populations). When computing the unbiased sample covariance, setting this parameter to 1 is the standard choice (i.e., the provided arrays contain data sampled from larger populations; this is commonly referred to as Bessel's correction).

Notes

• If provided an empty one-dimensional ndarray, the function returns NaN.

Examples

var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var ndarray = require( '@stdlib/ndarray/base/ctor' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
var scovarmtk = require( '@stdlib/stats/base/ndarray/scovarmtk' );

// Define array options:
var opts = {
    'dtype': 'float32'
};

// Create first one-dimensional ndarray containing pseudorandom integers drawn from a discrete uniform distribution:
var xbuf = discreteUniform( 10, -50, 50, opts );
var x = new ndarray( opts.dtype, xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
console.log( ndarray2array( x ) );

// Create second one-dimensional ndarray containing pseudorandom integers drawn from a discrete uniform distribution:
var ybuf = discreteUniform( 10, -50, 50, opts );
var y = new ndarray( opts.dtype, ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' );
console.log( ndarray2array( y ) );

// Specify the known means:
var meanx = scalar2ndarray( 0.0, opts );
var meany = scalar2ndarray( 0.0, opts );

// Specify the degrees of freedom adjustment:
var correction = scalar2ndarray( 1.0, opts );

// Calculate the sample covariance:
var v = scovarmtk( [ x, y, meanx, meany, correction ] );
console.log( v );