bootstrap

Bootstrap resampling utilities.

Installation

$ npm install compute-bootstrap

Usage

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

bootstrap( x, stat, r[, opts] )

Given input data in form of a matrix or array / typed array, this function generates bootstrap replications for the statistic(s) of interest as specified by the given stat function. The r argument denotes the number of bootstrap replications that should be generated. For each replication, stat will be invoked with the respective bootstrap sample passed as the first argument. If you wish to use the bootstrap for multiple statistics at once, the supplied stat function should return an array holding the individual statistics. For each statistic, the function returns an object with three properties:

• original: the statistic calculated for the original data set contained in x
• stdev: the bootstrap estimate of the standard error of the statistic
• bias: the difference between original and the bootstrap estimate of the mean for the statistic of interest, i.e. its sample mean calculated over all bootstrap replications

var data,
	median = require( 'compute-median' ),
	variance = require( 'compute-variance' ),
	out;

data = [
	3, 5, 8, 9, 1, 2, 12, 3, 22, 4, 8,
	12, 15, 18, 12, 7, 6, 4, 2, 0, 0, 1,
	3, 17, 5, 2, 19, 7, 17, 16
];

out = bootstrap( data, median, 1000, { seed: 22 } ;
/*
	{
		original: 6.5,
		stdev: 1.7594563611202991,
		bias: -0.15299999999999248
	}
*/

out = bootstrap( data, function( d ) {
	return [ median( d ), variance( d ) ];
}, 1000, { seed: 22 } );
/*
	[
		{
			original: 6.5,
			stdev: 1.7594563611202991,
			bias: -0.15299999999999248
		},
		{
			original: 41.58620689655172,
			stdev: 8.150566944052263,
			bias: -1.0566954022988782
		}
	]
*/

The function accepts the following options:

• seed: positive integer used as a seed to initialize the random number generator for creating the bootstrap replications.

The object returned by the bootstrap function (or the array elements in the case of multiple statistics) contains also non-enumerable properties realizations, data and statFun, which contain the realizations of the statistic for each bootstrap sample, the original data and the function used to calculate the statistic, respectively.

The package exports a function to calculate confidence intervals, which is described next.

.ci( out[, opts] )

With the ci function, one can construct confidence intervals. The out argument can be either a single output object or an array of output objects returned from bootstrap.

var rNorm = require( 'distributions-normal-random' ),
	data = rNorm( 1000, { mu: 3, sigma: 2, seed: 7 } ),
	out,
	ci;

out = bootstrap( data, median, 1000, { seed: 19 } );

// 95% CI for the median (using BCA method):
ci = bootstrap.ci( out )
// returns [ ~2.735, ~3.030 ]

The function accepts the following options:

• type: string denoting the type of confidence interval to create. Possible values are basic, bca, normal, percentile and studentized. Default: bca.
• level: number specifying confidence level of the interval. Default: 0.95.
• variance: If type is studentized, it is required to provide an array of estimates for the variance of the statistic in question at each bootstrap replication.

To calculate a confidence interval of a different type, use the type option:

ci = bootstrap.ci( out, { type: 'percentile' } );
// returns [ ~2.735, ~3.030 ]

See the corresponding Wikipedia article for an explanation of the various types.

To set the significance level to a different value than 0.95, use the level option:

bootstrap.ci( out, { level: 0.9 } )
// returns [ ~2.773, ~3.022 ]

If type is set to studentized, we need to supply a vector of variances for the `bootstrapped statistic at each bootstrap replication.

var mean = require( 'compute-mean' ),
	variance = require( 'compute-variance' );

out = bootstrap( data, function( d ) {
	var n = d.length;
	return [ mean( d ), variance( d ) / n ]
}, 500, { seed: 15 } );

bootstrap.ci( out[ 0 ], {
	type: 'studentized',
	variance: out[ 1 ].realizations
})
// returns [ ~2.978, ~3.074 ]

Examples

var bootstrap = require( 'compute-bootstrap' ),
	median = require( 'compute-median' ),
	variance = require( 'compute-variance' ),
	skewness = require( 'compute-skewness' ),
	rNorm = require( 'distributions-normal-random' ),
	data,
	out,
	ci;

// Bootstrap for sample median:
data = rNorm( 1000 );
out = bootstrap( data, median, 500 );

// Calculate different confidence intervals:
ci = bootstrap.ci( out, { type: 'bca', level: 0.95 } );
ci = bootstrap.ci( out, { type: 'percentile', level: 0.95 } );
ci = bootstrap.ci( out, { type: 'basic', level: 0.95 } );
ci = bootstrap.ci( out, { type: 'normal', level: 0.95 });

// Bootstrap for multiple statistics at once:
data = randomNormal( 1000 );
out = bootstrap( data, function( d ) {
	return [ skewness( d ), variance( d ) ];
}, 500 );

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. The Compute.io Authors.