Computes the natural logarithm of the binomial coefficient.
The binomialcoefln
function computes the natural logarithm of the binomial coefficient, i.e.
for any numbers n
and k
. Hence, the function supports the generalization of the binomial coefficient to negative integers and real numbers in general.
$ npm install compute-binomcoefln
For use in the browser, use browserify.
var binomcoefln = require( 'compute-binomcoefln' );
Computes the natural logarithm of the Binomial coefficient (element-wise). n
may be either a number
, an array
, a typed array
, or a matrix
. k
has to be either an array
or matrix
of equal dimensions as n
or a single number. Correspondingly, the function returns either an array
with the same length as the input array(s)
, a matrix
with the same dimensions as the input matrix/matrices
or a single number.
var matrix = require( 'dstructs-matrix' ),
data,
mat,
out,
i;
out = binomcoefln( 10, 2 );
// returns ~3.807
out = binomcoefln( 0, 0 );
// returns 0
/*
Handles negative numbers:
*/
out = binomcoefln( -1, 2 );
// returns 0
out = binomcoefln( -5, 4 );
// returns ~4.248
/*
Generalized version for real numbers:
*/
out = binomcoefln( 4.4, 2 );
// returns ~2.012
out = binomcoefln( 4.4, 1.5 );
// returns ~1.845
data = [ 0.5, 1, 1.5, 2, 2.5 ];
out = binomcoefln( data, 0.1 );
// returns [ ~0.049, ~0.089, ~0.118, ~0.140, ~0.159 ]
data = new Int8Array( data );
out = binomcoefln( data );
// returns Float64Array( [ ~0.049, ~0.089, ~0.118, ~0.140, ~0.159 ] )
data = new Float64Array( 6 );
for ( i = 0; i < 6; i++ ) {
data[ i ] = i / 2;
}
mat = matrix( data, [3,2], 'float64' );
/*
[ 0 0.5
1 1.5
2 2.5 ]
*/
out = binomcoefln( mat, 0.1 );
/*
[ ~-0.017 ~0.049
~0.089 ~0.118
~0.140 ~0.159 ]
*/
The function accepts the following options
:
- accessor: accessor
function
for accessingarray
values. - dtype: output
typed array
ormatrix
data type. Default:float64
. - copy:
boolean
indicating if thefunction
should return a new data structure. Default:true
. - path: deepget/deepset key path.
- sep: deepget/deepset key path separator. Default:
'.'
.
For non-numeric arrays
, provide an accessor function
for accessing array
values.
var data = [
['beep', 0.5 ],
['boop', 1 ],
['bip', 1.5 ],
['bap', 2 ],
['baz', 2.5 ]
];
function getValue( d, i ) {
return d[ 1 ];
}
var out = binomcoefln( data, 0.1, {
'accessor': getValue
});
// returns [ ~0.049, ~0.089, ~0.118, ~0.140, ~0.159 ]
When evaluating the Beta function for values of two object arrays
, provide an accessor function
which accepts 3
arguments.
var data = [
['beep', 0.5],
['boop', 1],
['bip', 1.5],
['bap', 2],
['baz', 2.5]
];
var k = [
{'x': 0.5},
{'x': 1},
{'x': 1.5.},
{'x': 2},
{'x': 2.5}
];
function getValue( d, i, j ) {
if ( j === 0 ) {
return d[ 1 ];
}
return d.x;
}
var out = beta( data, y, {
'accessor': getValue
});
// returns [ ~0, ~0, ~0, ~0, ~0 ]
Note: j
corresponds to the input array
index, where j=0
is the index for the first input array
and j=1
is the index for the second input array
.
To deepset an object array
, provide a key path and, optionally, a key path separator.
var data = [
{'x':[0,0.5]},
{'x':[1,1]},
{'x':[2,1.5]},
{'x':[3,2]},
{'x':[4,2.5]}
];
var out = binomcoefln( data, 0.1, 'x|1', '|' );
/*
[
{'x':[0,~0.049]},
{'x':[1,~0.089]},
{'x':[2,~0.118]},
{'x':[3,~0.140]},
{'x':[4,~0.159]}
]
*/
var bool = ( data === out );
// returns true
By default, when provided a typed array
or matrix
, the output data structure is float64
in order to preserve precision. To specify a different data type, set the dtype
option (see matrix
for a list of acceptable data types).
var data, out;
data = new Int8Array( [10,20,30] );
out = binomcoefln( data, {
'dtype': 'int32'
});
// returns Int32Array( [3,5,6] )
// Works for plain arrays, as well...
out = binomcoefln( [10,20,30], {
'dtype': 'uint8'
});
// returns Uint8Array( [3,5,6] )
By default, the function returns a new data structure. To mutate the input data structure (e.g., when input values can be discarded or when optimizing memory usage), set the copy
option to false
.
var data,
bool,
mat,
out,
i;
var data = [ 0.5, 1, 1.5, 2, 2.5 ];
var out = binomcoefln( data, 0.1, {
'copy': false
});
// returns [ ~0.049, ~0.089, ~0.118, ~0.140, ~0.159 ]
bool = ( data === out );
// returns true
data = new Float64Array( 6 );
for ( i = 0; i < 6; i++ ) {
data[ i ] = i / 2;
}
mat = matrix( data, [3,2], 'float64' );
/*
[ 0 0.5
1 1.5
2 2.5 ]
*/
out = binomcoefln( mat, 0.1, {
'copy': false
});
/*
[ ~-0.017 ~0.049
~0.089 ~0.118
~0.140 ~0.159 ]
*/
bool = ( mat === out );
// returns true
-
If an element is not a numeric value, the evaluated error function is
NaN
.var data, out; out = binomcoefln( null, 1 ); // returns NaN out = binomcoefln( true, 1 ); // returns NaN out = binomcoefln( {'a':'b'}, 1 ); // returns NaN out = binomcoefln( [ true, null, [] ], 1 ); // returns [ NaN, NaN, NaN ] function getValue( d, i ) { return d.x; } data = [ {'x':true}, {'x':[]}, {'x':{}}, {'x':null} ]; out = binomcoefln( data, 1, { 'accessor': getValue }); // returns [ NaN, NaN, NaN, NaN ] out = binomcoefln( data, 1, { 'path': 'x' }); /* [ {'x':NaN}, {'x':NaN}, {'x':NaN, {'x':NaN} ] */
-
Be careful when providing a data structure which contains non-numeric elements and specifying an
integer
output data type, asNaN
values are cast to0
.var out = binomcoefln( [ true, null, [] ], 0.1, { 'dtype': 'int8' }); // returns Int8Array( [0,0,0] );
var matrix = require( 'dstructs-matrix' ),
binomcoefln = require( 'compute-binomcoefln' );
var data,
mat,
out,
tmp,
i;
// Plain arrays...
data = new Array( 10 );
for ( i = 0; i < data.length; i++ ) {
data[ i ] = Math.round( Math.random()*20 );
}
out = binomcoefln( data, 3 );
// Object arrays (accessors)...
function getValue( d ) {
return d.x;
}
for ( i = 0; i < data.length; i++ ) {
data[ i ] = {
'x': data[ i ]
};
}
out = binomcoefln( data, 3, {
'accessor': getValue
});
// Deep set arrays...
for ( i = 0; i < data.length; i++ ) {
data[ i ] = {
'x': [ i, data[ i ].x ]
};
}
out = binomcoefln( data, 3, {
'path': 'x/1',
'sep': '/'
});
// Typed arrays...
data = new Int32Array( 10 );
for ( i = 0; i < data.length; i++ ) {
data[ i ] = Math.round( Math.random()*20 );
}
tmp = binomcoefln( data, 3 );
out = '';
for ( i = 0; i < data.length; i++ ) {
out += tmp[ i ];
if ( i < data.length-1 ) {
out += ',';
}
}
// Matrices...
mat = matrix( data, [5,2], 'int32' );
out = binomcoefln( mat, 3 );
// Matrices (custom output data type)...
out = binomcoefln( mat, 3, {
'dtype': 'uint8'
});
To run the example code from the top-level application directory,
$ node ./examples/index.js
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.
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
Copyright © 2015. The Compute.io Authors.