npm install compute-varianceVariance
===
[![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage Status][coveralls-image]][coveralls-url] [![Dependencies][dependencies-image]][dependencies-url]
> Computes the variance.
The population variance (biased sample variance) is defined as
and the unbiased sample variance is defined as
where x_0, x_1,...,x_{N-1} are individual data values and N is the total number of values in the data set.
Installation
`` bash`
$ npm install compute-variance
For use in the browser, use browserify.
Usage
` javascript`
var variance = require( 'compute-variance' );
$3
Computes the variance. x may be either an array, typed array, or matrix.
` javascript
var data, s2;
data = [ 2, 4, 5, 3, 4, 3, 1, 5, 6, 9 ];
s2 = variance( data );
// returns 5.067
data = new Int8Array( data );
s2 = variance( data );
// returns 5.067
`
For non-numeric arrays, provide an accessor function for accessing numeric array values.
` javascript
var data = [
{'x':2},
{'x':4},
{'x':5},
{'x':3},
{'x':4},
{'x':3},
{'x':1},
{'x':5},
{'x':6},
{'x':9}
];
function getValue( d ) {
return d.x;
}
var s2 = variance( data, {
'accessor': getValue
});
// returns 5.067
`
By default, the function calculates the unbiased sample variance. To calculate the population variance (or a biased sample variance), set the bias option to true.
` javascript
var data = [ 2, 4, 5, 3, 4, 3, 1, 5, 6, 9 ];
var sigma2 = variance( data, {
'bias': true
});
// returns 4.56
`
If provided a matrix, the function accepts the following additional options:
* __dim__: dimension along which to compute the variance. Default: 2 (along the columns).matrix
* __dtype__: output data type. Default: float64.
By default, the function computes the variance along the columns (dim=2).
` javascript
var matrix = require( 'dstructs-matrix' ),
data,
mat,
s2,
i;
data = new Int8Array( 25 );
for ( i = 0; i < data.length; i++ ) {
data[ i ] = i;
}
mat = matrix( data, [5,5], 'int8' );
/*
[ 0 1 2 3 4
5 6 7 8 9
10 11 12 13 14
15 16 17 18 19
20 21 22 23 24 ]
*/
s2 = variance( mat );
/*
[ 2.5
2.5
2.5
2.5
2.5 ]
*/
`
To compute the variance along the rows, set the dim option to 1.
` javascript`
s2 = variance( mat, {
'dim': 1
});
/*
[ 62.5, 62.5, 62.5, 62.5, 62.5 ]
*/
By default, the output matrix data type is float64. To specify a different output data type, set the dtype option.
` javascript
s2 = variance( mat, {
'dim': 1,
'dtype': 'uint8'
});
/*
[ 62.5, 62.5, 62.5, 62.5, 62.5 ]
*/
var dtype = s2.dtype;
// returns 'uint8'
`
If provided a matrix having either dimension equal to 1, the function treats the matrix as a typed array and returns a numeric value.
` javascript
data = [ 2, 4, 5, 3, 4, 3, 1, 5, 6, 9 ];
// Row vector:
mat = matrix( new Int8Array( data ), [1,10], 'int8' );
s2 = variance( mat );
// returns 5.067
// Column vector:
mat = matrix( new Int8Array( data ), [10,1], 'int8' );
s2 = variance( mat );
// returns 5.067
`
If provided an empty array, typed array, or matrix, the function returns null.
` javascript
s2 = variance( [] );
// returns null
s2 = variance( new Int8Array( [] ) );
// returns null
s2 = variance( matrix( [0,0] ) );
// returns null
s2 = variance( matrix( [0,10] ) );
// returns null
s2 = variance( matrix( [10,0] ) );
// returns null
`
Examples
` javascript
var matrix = require( 'dstructs-matrix' ),
variance = require( 'compute-variance' );
var data,
mat,
s2,
i;
// Plain arrays...
var data = new Array( 100 );
for ( var i = 0; i < data.length; i++ ) {
data[ i ] = Math.round( Math.random() * 10 + 1 );
}
s2 = variance( data );
// Object arrays (accessors)...
function getValue( d ) {
return d.x;
}
for ( i = 0; i < data.length; i++ ) {
data[ i ] = {
'x': data[ i ]
};
}
s2 = variance( data, {
'accessor': getValue
});
// Typed arrays...
data = new Int32Array( 100 );
for ( i = 0; i < data.length; i++ ) {
data[ i ] = Math.round( Math.random() * 10 + 1 );
}
s2 = variance( data );
// Matrices (along rows)...
mat = matrix( data, [10,10], 'int32' );
s2 = variance( mat, {
'dim': 1
});
// Matrices (along columns)...
s2 = variance( mat, {
'dim': 2
});
// Matrices (custom output data type)...
s2 = variance( mat, {
'dtype': 'uint8'
});
`
To run the example code from the top-level application directory,
` bash`
$ node ./examples/index.js
Tests
$3
Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:
` bash`
$ make test
All new feature development should have corresponding unit tests to validate correct functionality.
$3
This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:
` bash`
$ make test-cov
Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,
` bash``
$ make view-cov
---
License
Copyright
Copyright © 2014-2015. The Compute.io Authors.
[npm-image]: http://img.shields.io/npm/v/compute-variance.svg
[npm-url]: https://npmjs.org/package/compute-variance
[travis-image]: http://img.shields.io/travis/compute-io/variance/master.svg
[travis-url]: https://travis-ci.org/compute-io/variance
[coveralls-image]: https://img.shields.io/coveralls/compute-io/variance/master.svg
[coveralls-url]: https://coveralls.io/r/compute-io/variance?branch=master
[dependencies-image]: http://img.shields.io/david/compute-io/variance.svg
[dependencies-url]: https://david-dm.org/compute-io/variance
[dev-dependencies-image]: http://img.shields.io/david/dev/compute-io/variance.svg
[dev-dependencies-url]: https://david-dm.org/dev/compute-io/variance
[github-issues-image]: http://img.shields.io/github/issues/compute-io/variance.svg
[github-issues-url]: https://github.com/compute-io/variance/issues