Beta Random Variables

Creates a matrix or array filled with draws from a beta distribution.

Installation

$ npm install distributions-beta-random

For use in the browser, use browserify.

Usage

var random = require( 'distributions-beta-random' );

random( [dims][, opts] )

Creates a matrix or array filled with draws from a beta distribution. The dims argument may either be a positive integer specifying a length or an array of positive integers specifying dimensions. If no dims argument is supplied,the function returns a single random draw from a beta distribution.

var out;

// Set seed
random.seed = 2;

out = random( 5 );
// returns [ ~0.376, ~0.453, ~0.963, ~0.523, ~0.287 ]

out = random( [2,1,2] );
// returns [ [ [~0.684,~0.296] ], [ [~0.860,~0.646] ] ]

The function accepts the following options:

alpha: first shape parameter. Default: 1.
beta: second shape parameter. Default: 1.
seed: positive integer used as a seed to initialize the generator. If not supplied, uniformly distributed random numbers are generated via an underlying generator seedable by setting the seed property of the exported function.
dtype: output data type (see matrix for a list of acceptable data types). Default: generic.

The beta distribution is a function of two parameters: alpha > 0(first shape parameter) and beta > 0(second shape parameter). By default, alpha is equal to 1 and beta is equal to 1. To adjust either parameter, set the corresponding option.

var out = random( 5, {
	'alpha': 30,
	'beta': 5,
});
// returns [ ~0.898, ~0.916, ~0.892, ~0.853, ~0.752 ]

To be able to reproduce the generated random numbers, set the seed option to a positive integer.

var out;
out = random( 3, {
	'seed': 22
});
// returns [ ~0.203, ~0.642, ~0.123 ]

out = random( 3, {
	'seed': 22
});
// returns [ ~0.203, ~0.642, ~0.123 ]

If no seed option is supplied, each function call uses a common underlying uniform number generator. A positive-integer seed for this underlying generator can be supplied by setting the seed property of the exported function.

var out;

random.seed = 11;
out = random();
// returns ~0.211

out = random();
// returns ~0.179

random.seed = 11;
out = random();
// returns ~0.211

out = random();
// returns ~0.179

By default, the output data structure is a generic array. To output a typed array or matrix, set the dtype option.

var out;

out = random( 5, {
	'dtype': 'float32'
});
// returns Float32Array( [~0.687,~0.599,~0.771,~0.901,~0.942] )

out = random( [3,2], {
	'dtype': 'float64'
});
/*
	[ ~0.163 ~0.683
	  ~0.604 ~0.629
	  ~0.885 ~0.993 ]
*/

Notes:

Currently, for more than 2 dimensions, the function outputs a generic array and ignores any specified dtype.

var out = random( [2,1,3], {
	'dtype': 'float32'
});
// returns [ [ [~0.914,~0.264,~0.306] ], [ [~0.962,0.407,~0.966] ] ]

Method

The algorithm used to generate beta random variables depends on the parameter inputs. In cases where alpha equals beta and both exceed 1.5 or when alpha>1 and beta>1, the function uses the BN and BS algorithms developed by Ahrens & Dieter.

In all other cases, the function generates gamma distributed variates X and Y with parameters alpha and beta by drawing X ~ Gamma( alpha, 1 ) and Y ~ Gamma( beta, 1) via gamma-random and returning X / ( X + Y).

To generate the random standard normal variates, the module internally calls the normal-random which provides a very fast algorithm, the improved Ziggurat algorithm by Doornik, to sample from a normal distribution.

Reference:

Ahrens, J. H., & Dieter, U. (1974). Computer methods for sampling from gamma, beta, poisson and bionomial distributions. Computing, 12(3), 223–246. doi:10.1007/BF02293108

Doornik, J. a. (2005). An Improved Ziggurat Method to Generate Normal Random Samples.

Examples

var random = require( 'distributions-beta-random' ),
	out;

// Set seed
random.seed = 4;

// Plain arrays...

// 1x10:
out = random( 10 );

// 2x1x3:
out = random( [2,1,3] );

// 5x5x5:
out = random( [5,5,5] );

// 10x5x10x20:
out = random( [10,5,10,20] );

// Typed arrays...
out = random( 10, {
	'dtype': 'float32'
});

// Matrices...
out = random( [3,2], {
	'dtype': 'float64'
});

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.

distributions-io/beta-random