Truncated Mean

Computes the truncated mean of an array.

Installation

$ npm install compute-truncmean

For use in the browser, use browserify.

Usage

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

truncmean( arr, discard[, options] )

Computes the truncated mean of an array. The truncated mean is an order statistic, meaning that the statistic is computed over an ordered representation having length N. The discard parameter specifies how many values are excluded when computing the statistic. When expressed as a percentage p on the interval [0,0.5], N*p values are excluded from the low end of the input array and another N*p values are excluded from the high end of the input array. When expressed as an integer n < N/2, n values are excluded from the low end and another n values are excluded from the high end.

var data = [ 2, 4, 5, 3, 8, 2, 4, 4, 100, 0 ];

var mu = truncmean( data, 0.1 );
// returns 4

If discard = 0, then the result is equivalent to the mean. If discard = 0.5, then the result is equivalent to the median. If discard = 0.25, then the result is equivalent to the interquartile mean.

The function accepts three options:

• sorted: boolean indicating if the input array is sorted in ascending order. Default: false.
• accessor: accessor function for accessing values in object arrays.
• interpolate: boolean indicating whether the mean should be interpolated if a discard percentage does not yield an integer number of values. Default: false.

If the input array is already sorted in ascending order, set the sorted option to true.

var data = [ 0, 2, 2, 3, 4, 4, 4, 5, 8, 100 ];

var mu = truncmean( data, 2, {
	'sorted': true
});
// returns ~3.67

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

var data = [
    {'x':2},
    {'x':4},
    {'x':5},
    {'x':3},
    {'x':8},
    {'x':2},
    {'x':4},
    {'x':4},
    {'x':100},
    {'x':0}
];

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

var mu = truncmean( data, 0.1, {
	'accessor': getValue
});
// returns 4

To interpolate between truncated means if a discard percentage does not yield an integer number of values to discard, set the interpolate option to true.

 var data = [ 2, 4, 5, 3, 8, 2, 4, 4, 100, 0 ];

var mu = truncmean( data, 0.19, {
	'interpolate': true
});
// returns ~3.70

Notes

• if provided an empty array, the function returns null.
• the discard amount is applied to both "ends" of the (sorted) input array. For example, if discard = 0.1, 10% of the largest values and 10% of the smallest values are discarded.
• interpolation is a weighted average between truncated means having ⌈N*p⌉ and ⌊N*p⌋ number of values discarded, where N is the input array length and p is the discard percentage. For example, if N = 10 and p = 0.19, then the interpolated mean is 0.1*mu_{floor} + 0.9*mu_{ceil}.

Examples

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

// Simulate some data...
var data = new Array( 1000 );
for ( var i = 0; i < data.length; i++ ) {
    data[ i ] = Math.random() * 100;
}

// Calculate the truncated mean...
console.log( truncmean( data, 0.1 ) );

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

$ node ./examples/index.js

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 © 2015. Philipp Burckhardt.