Refactoring to provide matrix support

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Athan Reines.
+Copyright (c) 2015 The Compute.io Authors. All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

Makefile

@@ -5,6 +5,14 @@
 # Set the node.js environment to test:
 NODE_ENV ?= test
 
+# Kernel name:
+KERNEL ?= $(shell uname -s)
+
+ifeq ($(KERNEL), Darwin)
+	OPEN ?= open
+else
+	OPEN ?= xdg-open
+endif
 
 # NOTES #
 
@@ -98,8 +106,7 @@ test-istanbul-mocha: node_modules
 view-cov: view-istanbul-report
 
 view-istanbul-report:
-	open $(ISTANBUL_HTML_REPORT_PATH)
-
+	$(OPEN) $(ISTANBUL_HTML_REPORT_PATH)
 
 
 # LINT #

README.md

@@ -2,7 +2,23 @@ Variance
 ===
 [![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](http://en.wikipedia.org/wiki/Variance) of an array.
+> Computes the [variance](http://en.wikipedia.org/wiki/Variance).
+
+The [population variance](http://en.wikipedia.org/wiki/Variance) (biased sample variance) is defined as
+
+<div class="equation" align="center" data-raw-text="\sigma^2 = \frac{1}{N} \sum_{i=0}^{N-1} \left(x_i - \overline{x} \right)^2" data-equation="eq:population_variance">
+	<img src="https://cdn.rawgit.com/compute-io/variance/2b812a7ecb17a847cc39ed5730f13114636553d4/docs/img/eqn2.svg" alt="Equation for the population (biased sample) variance.">
+	<br>
+</div>
+
+and the unbiased [sample variance](http://en.wikipedia.org/wiki/Variance) is defined as
+
+<div class="equation" align="center" data-raw-text="s^2 = \frac{1}{N-1} \sum_{i=0}^{N-1} \left(x_i - \overline{x} \right)^2" data-equation="eq:sample_variance">
+	<img src="https://cdn.rawgit.com/compute-io/variance/bdaaeaeb1718476b61f462cf3e5252d7b4c0c585/docs/img/eqn.svg" alt="Equation for the unbiased sample variance.">
+	<br>
+</div>
+
+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
@@ -20,23 +36,23 @@ For use in the browser, use [browserify](https://github.com/substack/node-browse
 var variance = require( 'compute-variance' );
 ```
 
-### variance( arr[, opts] )
+### variance( x[, opts] )
 
-Computes the [variance](http://en.wikipedia.org/wiki/Variance) of an `array`. For numeric `arrays`,
+Computes the [variance](http://en.wikipedia.org/wiki/Variance). `x` may be either an [`array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), [`typed array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays), or [`matrix`](https://github.com/dstructs/matrix).
 
 ``` javascript
-var data = [ 2, 4, 5, 3, 4, 3, 1, 5, 6, 9 ];
+var data, s2;
 
-var s2 = variance( data );
+data = [ 2, 4, 5, 3, 4, 3, 1, 5, 6, 9 ];
+s2 = variance( data );
 // returns 5.067
-```
-
-The function accepts two `options`:
 
-*	__accessor__: accessor `function` for accessing `array` values
-*	__bias__: `boolean` indicating whether to compute the population variance (biased sample variance) or the (unbiased) sample variance. Default: `false`; i.e., the unbiased sample variance.
+data = new Int8Array( data );
+s2 = variance( data );
+// returns 5.067
+```
 
-For non-numeric `arrays`, provide an accessor `function` for accessing numeric `array` values
+For non-numeric `arrays`, provide an accessor `function` for accessing numeric `array` values.
 
 ``` javascript
 var data = [
@@ -62,32 +78,170 @@ var s2 = variance( data, {
 // 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`.
+By default, the function calculates the *unbiased* sample [variance](http://en.wikipedia.org/wiki/Variance). To calculate the population [variance](http://en.wikipedia.org/wiki/Variance) (or a *biased* sample [variance](http://en.wikipedia.org/wiki/Variance)), set the `bias` option to `true`.
 
 ``` javascript
 var data = [ 2, 4, 5, 3, 4, 3, 1, 5, 6, 9 ];
 
-var value = variance( data, {
-	'bias': true	
+var sigma2 = variance( data, {
+	'bias': true
 });
 // returns 4.56
 ```
 
-__Note__: if provided an empty `array`, the function returns `null`.
+If provided a [`matrix`](https://github.com/dstructs/matrix), the function accepts the following additional `options`:
+
+*	__dim__: dimension along which to compute the [variance](http://en.wikipedia.org/wiki/Variance). Default: `2` (along the columns).
+*	__dtype__: output [`matrix`](https://github.com/dstructs/matrix) data type. Default: `float64`.
+
+By default, the function computes the [variance](http://en.wikipedia.org/wiki/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](http://en.wikipedia.org/wiki/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`](https://github.com/dstructs/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`](https://github.com/dstructs/matrix) having either dimension equal to `1`, the function treats the [`matrix`](https://github.com/dstructs/matrix) as a [`typed array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays) 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), [`typed array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays), or [`matrix`](https://github.com/dstructs/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 variance = require( 'compute-variance' );
+var matrix = require( 'dstructs-matrix' ),
+	variance = require( 'compute-variance' );
 
-var data = new Array( 1000 );
+var data,
+	mat,
+	s2,
+	i;
+
+// Plain arrays...
+var data = new Array( 100 );
 for ( var i = 0; i < data.length; i++ ) {
-	data[ i ] = Math.random() * 100;
+	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
+});
 
-console.log( variance( data ) );
+// 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,
@@ -131,7 +285,7 @@ $ make view-cov
 
 ## Copyright
 
-Copyright &copy; 2014. Athan Reines.
+Copyright &copy; 2014-2015. The [Compute.io](https://github.com/compute-io) Authors.
 
 
 [npm-image]: http://img.shields.io/npm/v/compute-variance.svg

TODO.md

@@ -1,3 +1,2 @@
 TODO
 ====
-