Refactoring to provide matrix support

.npmignore

@@ -49,4 +49,4 @@ Desktop.ini
 .jshintrc
 .jshintignore
 .travis.yml
-.editorconfig
+.editorconfig

.travis.yml

@@ -9,3 +9,4 @@ before_install:
   - npm update -g npm
 after_script:
   - npm run coveralls
+

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014-2015 Rebekah Smith.
+Copyright (c) 2014-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 #
 
@@ -30,7 +38,7 @@ ISTANBUL_HTML_REPORT_PATH ?= $(ISTANBUL_OUT)/lcov-report/index.html
 # JSHINT #
 
 JSHINT ?= ./node_modules/.bin/jshint
-JSHINT_REPORTER ?= ./node_modules/jshint-stylish/stylish.js
+JSHINT_REPORTER ?= ./node_modules/jshint-stylish
 
 
 
@@ -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,8 +2,16 @@ Geometric Mean
 =====
 [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage][coveralls-image]][coveralls-url] [![Dependencies][dependencies-image]][dependencies-url]
 
-> Computes the [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean) of an array.
+> Computes the [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean).
 
+The [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean) is defined as
+
+<div class="equation" align="center" data-raw-text="G = \left(\prod_{i=0}^{N-1} x_i\right)^{1/N}" data-equation="eq:geometric_mean">
+	<img src="https://cdn.rawgit.com/compute-io/gmean/3ec3ab46db1ae39b3049c22e9e3d533bb2067d85/docs/img/eqn1.svg" alt="Equation for the geometric mean.">
+	<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
 
@@ -17,49 +25,200 @@ $ npm install compute-gmean
 var gmean = require( 'compute-gmean' );
 ```
 
-#### gmean( arr[, accessor] )
+#### gmean( x[, opts] )
 
-Computes the [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean) of an `array`. For numeric `arrays`,
+Computes the [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean).  `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 = [ 1, 5, 2, 3, 7 ];
+var data, mu;
+
+data = [ 1, 5, 2, 3, 7 ];
+mu = gmean( data );
+// returns ~2.914
 
-var mu = gmean( data );
+data = new Int8Array( data );
+mu = gmean( data );
 // returns ~2.914
 ```
 
-For non-numeric `arrays`, provide an accessor `function` for accessing numeric values
+Notes:
+
+1. Only calculate the [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean) of an `array` of __positive__ numbers. The textbook formula for calculating the geometric mean involves taking the product of all `array` elements. If one element is `0`, then the product is `0`, even if all other values are `>>> 0`, yielding a nonsensical geometric mean (and measure of the central tendency). Nonsensical results also arise when an `array` contains negative values leading to a product without positive roots and a geometric mean which does not map to the measure's geometric interpretation. For more information, see *Handbook of Parametric and Nonparametric Statistical Procedures: Third Edition* by David J. Sheskin.
+2. If an `array` contains values less than or equal to `0`, the function returns `NaN`.
+3. For arrays exceeding memory constraints, you are encouraged to use streams; see [flow-gmean](https://github.com/flow-io/flow-gmean).
+
+For non-numeric `arrays`, provide an accessor `function` for accessing `array` values.
 
 ``` javascript
-var arr = [
+var data = [
 	{'x':1},
 	{'x':5},
 	{'x':2},
 	{'x':3},
 	{'x':7}
-]:
+];
 
-function getValue( d ) {
+function getValue( d, i ) {
 	return d.x;
 }
 
-var value = prod( arr, getvalue );
+var mu = gmean( data, {
+	'accessor': getValue
+});
 // returns ~2.194
 ```
 
+If provided a [`matrix`](https://github.com/dstructs/matrix), the function accepts the following `options`:
+
+*	__dim__: dimension along which to compute the [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean). Default: `2` (along the columns).
+*	__dtype__: output [`matrix`](https://github.com/dstructs/matrix) data type. Default: `float64`.
+
+By default, the function computes the [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean) along the columns (`dim=2`).
+
+``` javascript
+var matrix = require( 'dstructs-matrix' ),
+	data,
+	mat,
+	mu,
+	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 ]
+*/
+
+mu = gmean( mat );
+/*
+	[  NaN
+	   6.853
+	  11.916
+	  16.941
+	  21.954 ]
+*/
+```
+
+To compute the [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean) along the rows, set the `dim` option to `1`.
+
+``` javascript
+mu = gmean( mat, {
+	'dim': 1
+});
+/*
+	[ NaN, 7.399, 9.112, 10.525, 11.811 ]
+*/
+```
+
+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
+mu = gmean( mat, {
+	'dim': 1,
+	'dtype': 'uint8'
+});
+/*
+	[ 0, 7, 9, 10, 11 ]
+*/
+
+var dtype = mu.dtype;
+// returns 'uint8'
+```
+
+Note: `NaN` will be coerced to `0` for [`typed arrays`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays) of type integer. Only typed arrays of type `float64` and `float32` can hold `NaN` values.
+
+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 = [ 1, 5, 2, 3, 7 ];
+
+// Row vector:
+mat = matrix( new Int8Array( data ), [1,5], 'int8' );
+mu = gmean( mat );
+// returns ~2.194
+
+// Column vector:
+mat = matrix( new Int8Array( data ), [5,1], 'int8' );
+mu = gmean( mat );
+// returns ~2.194
+```
+
+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
+mu = gmean( [] );
+// returns null
+
+mu = gmean( new Int8Array( [] ) );
+// returns null
+
+mu = gmean( matrix( [0,0] ) );
+// returns null
+
+mu = gmean( matrix( [0,10] ) );
+// returns null
+
+mu = gmean( matrix( [10,0] ) );
+// returns null
+```
 
 ## Examples
 
 ``` javascript
-var gmean = require( 'compute-gmean' );
+var matrix = require( 'dstructs-matrix' ),
+	gmean = require( 'compute-gmean' );
+
+var data,
+	mat,
+	mu,
+	i;
 
-var data = new Array( 1000 );
-for ( var i = 0; i < data.length; i++ ) {
+// Plain arrays...
+data = new Array( 1000 );
+for ( i = 0; i < data.length; i++ ) {
 	data[ i ] = Math.random() * 100;
 }
+mu = gmean( data );
 
-console.log( gmean( data ) );
+// Object arrays (accessors)...
+function getValue( d ) {
+	return d.x;
+}
+for ( i = 0; i < data.length; i++ ) {
+	data[ i ] = { 'x': data[ i ] };
+}
+mu = gmean( data, {
+	'accessor': getValue
+});
+
+// Typed arrays...
+data = new Int32Array( 1000 );
+for ( i = 0; i < data.length; i++ ) {
+	data[ i ] = Math.random() * 100;
+}
+mu = gmean( data );
+
+// Matrices (along rows)...
+mat = matrix( data, [100,10], 'int32' );
+mu = gmean( mat, {
+	'dim': 1
+});
+
+// Matrices (along columns)...
+mu = gmean( mat, {
+	'dim': 2
+});
+
+// Matrices (custom output data type)...
+mu = gmean( mat, {
+	'dtype': 'uint8'
+});
 ```
 
 To run the example code from the top-level application directory,
@@ -68,16 +227,6 @@ To run the example code from the top-level application directory,
 $ node ./examples/index.js
 ```
 
-
-
-## Notes
-
-1. Only calculate the [geometric mean](http://en.wikipedia.org/wiki/Geometric_mean) of an `array` of __positive__ numbers. The textbook formula for calculating the geometric mean involves taking the product of all `array` elements. If one element is `0`, then the product is `0`, even if all other values are `>>> 0`, yielding a nonsensical geometric mean (and measure of the central tendency). Nonsensical results also arise when an `array` contains negative values leading to a product without positive roots and a geometric mean which does not map to the measure's geometric interpretation. For more information, see *Handbook of Parametric and Nonparametric Statistical Procedures: Third Edition* by David J. Sheskin.
-2. If an `array` contains values less than or equal to `0`, the function returns `NaN`.
-3. If provided an empty `array`, the function returns `null`.
-4. For arrays exceeding memory constraints, you are encouraged to use streams; see [flow-gmean](https://github.com/flow-io/flow-gmean).
-
-
 ## Tests
 
 ### Unit
@@ -109,11 +258,11 @@ $ make view-cov
 ---
 ## License
 
-[MIT license](http://opensource.org/licenses/MIT). 
+[MIT license](http://opensource.org/licenses/MIT).
 
 ## Copyright
 
-Copyright &copy; 2014-2015. Rebekah Smith.
+Copyright &copy; 2014-2015. The [Compute.io](https://github.com/compute-io) Authors.
 
 
 [npm-image]: http://img.shields.io/npm/v/compute-gmean.svg