# incrcovmat
> Compute an [unbiased sample covariance matrix][covariance-matrix] incrementally.
A [covariance matrix][covariance-matrix] is an M-by-M matrix whose elements specified by indices `j` and `k` are the [covariances][covariance-matrix] between the jth and kth data variables. For unknown population means, the [unbiased sample covariance][covariance-matrix] is defined as
For known population means, the [unbiased sample covariance][covariance-matrix] is defined as
## Usage
```javascript
var incrcovmat = require( '@stdlib/stats/incr/covmat' );
```
#### incrcovmat( out\[, means] )
Returns an accumulator `function` which incrementally computes an [unbiased sample covariance matrix][covariance-matrix].
```javascript
// 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][covariance-matrix] or a square 2-dimensional [`ndarray`][@stdlib/ndarray/ctor] for storing the [unbiased sample covariance matrix][covariance-matrix].
```javascript
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`][@stdlib/ndarray/ctor] containing mean values.
```javascript
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][covariance-matrix]. If not provided a data vector, the accumulator function returns the current [unbiased sample covariance matrix][covariance-matrix].
```javascript
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
var bool = ( out === cov );
// returns true
vec.set( 0, 1.0 );
vec.set( 1, -5.0 );
out = accumulator( vec );
// returns
vec.set( 0, 3.0 );
vec.set( 1, 3.14 );
out = accumulator( vec );
// returns
out = accumulator();
// returns
```
## Examples
```javascript
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 );
}
```
[covariance-matrix]: https://en.wikipedia.org/wiki/Covariance_matrix
[@stdlib/ndarray/ctor]: https://www.npmjs.com/package/@stdlib/ndarray-ctor
