compute-qmean

Quadratic Mean

Computes the quadratic mean (root mean square; rms).

The quadratic mean 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

$ npm install compute-qmean

For use in the browser, use browserify.

Usage

var qmean = require( 'compute-qmean' );

qmean( x[, opts] )

Computes the quadratic mean (root mean square). x may be either an array, typed array, or matrix.

var data, mu;

data = [ 2, 7, 3, -3, 9 ];

mu = qmean( data );
// returns ~5.5136

data = new Int8Array( data );
mu = qmean( data );
// returns ~5.5136

For non-numeric arrays, provide an accessor function for accessing array values.

var data = [
	{'x':2},
	{'x':7},
	{'x':3},
	{'x':-3},
	{'x':9}
];

function getValue( d, i ) {
	return d.x;
}

var mu = qmean( data, {
	'accessor': getValue
});
// returns ~5.5136

If provided a matrix, the function accepts the following options:

• dim: dimension along which to compute the quadratic mean. Default: 2 (along the columns).
• dtype: output matrix data type. Default: float64.

By default, the function computes the quadratic mean along the columns (dim=2).

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 = qmean( mat );
/*
	[  2.449
	   7.141
	  12.083
	  17.059
	  22.045 ]
*/

To compute the quadratic mean along the rows, set the dim option to 1.

mu = qmean( mat, {
	'dim': 1
});
/*
	[ 12.247, 13.077, 13.928, 14.799, 15.684 ]
*/

By default, the output matrix data type is float64. To specify a different output data type, set the dtype option.

mu = qmean( mat, {
	'dim': 1,
	'dtype': 'uint8'
});
/*
	[ 12, 13, 13, 14, 15 ]
*/

var dtype = mu.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.

data = [ 2, 4, 5, 3, 8, 2 ];

// Row vector:
mat = matrix( new Int8Array( data ), [1,6], 'int8' );
mu = qmean( mat );
// returns ~4.509

// Column vector:
mat = matrix( new Int8Array( data ), [6,1], 'int8' );
mu = qmean( mat );
// returns ~4.509

If provided an empty array, typed array, or matrix, the function returns null.

mu = qmean( [] );
// returns null

mu = qmean( new Int8Array( [] ) );
// returns null

mu = qmean( matrix( [0,0] ) );
// returns null

mu = qmean( matrix( [0,10] ) );
// returns null

mu = qmean( matrix( [10,0] ) );
// returns null

Examples

var matrix = require( 'dstructs-matrix' ),
	qmean = require( 'compute-qmean' );

var data,
	mat,
	mu,
	i;


// ----
// Plain arrays...
data = new Array( 1000 );
for ( i = 0; i < data.length; i++ ) {
	data[ i ] = Math.random() * 100;
}
mu = qmean( data );
console.log( 'Arrays: %d\n', mu );


// ----
// Object arrays (accessors)...
function getValue( d ) {
	return d.x;
}
for ( i = 0; i < data.length; i++ ) {
	data[ i ] = {
		'x': data[ i ]
	};
}
mu = qmean( data, {
	'accessor': getValue
});
console.log( 'Accessors: %d\n', mu );


// ----
// Typed arrays...
data = new Int32Array( 1000 );
for ( i = 0; i < data.length; i++ ) {
	data[ i ] = Math.random() * 100;
}
mu = qmean( data );
console.log( 'Typed arrays: %d\n', mu );


// ----
// Matrices (along rows)...
mat = matrix( data, [100,10], 'int32' );
mu = qmean( mat, {
	'dim': 1
});
console.log( 'Matrix (rows): %s\n', mu.toString() );


// ----
// Matrices (along columns)...
mu = qmean( mat, {
	'dim': 2
});
console.log( 'Matrix (columns): %s\n', mu.toString() );


// ----
// Matrices (custom output data type)...
mu = qmean( mat, {
	'dtype': 'uint8'
});
console.log( 'Matrix (%s): %s\n', mu.dtype, mu.toString() );

To run the example code from the top-level application directory,

$ node ./examples/index.js

Notes

The algorithm to compute the quadratic mean first calculates the L2 norm before dividing by the square root of the number of elements. This particular implementation attempts to avoid overflow and underflow and is accurate to <1e-13 compared to the canonical formula for calculating the root mean square.

References

• Dahlquist, Germund and Bjorck, Ake. Numerical Methods in Scientific Computing.
• Blue, James (1978) "A Portable Fortran Program To Find the Euclidean Norm of a Vector". ACM Transactions on Mathematical Software.
• Higham, Nicholas J. Accuracy and Stability of Numerical Algorithms, Second Edition.

This module implements a one-pass algorithm proposed by S.J. Hammarling.

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

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:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

License

MIT license.

Copyright

Copyright © 2014-2015. The Compute.io Authors.