Package Exports

compute.io

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (compute.io) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Compute.io

Computation library.

```
[Installation](#installation)
```
```
[Usage](#usage)
```
- ```
[Utilities](#utilities)
```
  - ```
  [roundn( x, n )](#roundn)
```
- polyval( coef, x )
- reverse( arr )
- shuffle( arr )
- diff( arr )
- Special Functions
- ```
[Sets](#sets)
```
  - unique( arr, sorted )
- Linear Algebra
  - ```
  [l1norm( arr )](#l1norm)
```
- ```
[l2norm( arr )](#l2norm)
```
  - ```
  [linfnorm( arr )](#linfnorm)
```
- ```
[lpnorm( arr )](#lpnorm)
```
- ```
[Statistics](#statistics)
```
- Geometry
  - hypot( a, b )
- ```
[Information Theory](#information-theory)
```
  - hamdist( a, b )
```
[Fluent Interface](#fluent-interface)
```
```
[Tests](#tests)
```
- ```
[Unit](#unit)
```
- Coverage
```
[License](#license)
```

Installation

$ npm install compute.io

Usage

To use compute,

var compute = require( 'compute.io' );

The compute module is comprised of several smaller modules. If you want to roll your own compute, follow the links and import the individual modules.

The compute module has the following methods...

Utilities

compute.roundn( x, n )

Rounds values to the nearest multiple of 10^n. x may be either a single numeric value or an array of values. n must be an integer.

console.log( compute.roundn( Math.PI, -2 ) );
// returns 3.14

console.log( compute.roundn( 111, 2 ) );
// returns 100

var data = [ 2.342, 4.943, 2.234, 7.992, 3.142 ];

console.log( compute.roundn( data, -2 ) );
// returns [...] where each value is rounded to nearest hundredth

compute.polyval( coef, x )

Evaluates a polynomial with coefficients coef, where x may be a single numeric value or an array of numeric values.

var coef = [ 4, 2, 6, -17 ];

console.log( compute.polyval( coef, [ 10, -3] ) );

compute.reverse( arr )

Reverses an array in place.

var arr = [ 1, 2, 3, 4 ];

console.log( reverse( arr ) );
// returns [ 4, 3, 2, 1 ];

Note: the array is mutated.

compute.shuffle( arr )

Generates a random permutation of (shuffles) an array in place.

var arr = [ 1, 2, 3, 4 ];

console.log( shuffle( arr ) );

Note: the array is mutated.

compute.diff( arr )

Calculates the differences between adjacent elements in an array.

var arr = [ 2, 1, 3, 4 ];

console.log( diff( arr ) );
// returns [ 1, -2, -1 ];

Note: the length of the returned array is one less than the length of the original array.

Special Functions

compute.signum( x )

Evaluates the signum function, where x may be a single numeric value or an array of numeric values.

var data = [ -10, -1, -0, 0, 1, 10 ];

console.log( compute.signum( data ) );

compute.erf( x )

Evaluates the error function, where x may be a single numeric value or an array of numeric values.

var data = [ -10, -1, 0, 1, 10 ];

console.log( compute.erf( data ) );

compute.erfc( x )

Evaluates the complementary error function, where x may be a single numeric value or an array of numeric values.

var data = [ -10, -1, 0, 1, 10 ];

console.log( compute.erfc( data ) );

compute.erfinv( x )

Evaluates the inverse error function, where x may be a single numeric value or an array of numeric values.

var data = [ -1, -0.5, 0, 0.5, 1 ];

console.log( compute.erfinv( data ) );

compute.erfcinv( x )

Evaluates the inverse complementary error function, where x may be a single numeric value or an array of numeric values.

var data = [ 0, 0.5, 1, 1.5, 2 ];

console.log( compute.erfcinv( data ) );

Sets

compute.unique( arr[, sorted] )

Removes duplicate values to determine the subset containing all unique values of a numeric array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.unique( data ) );

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

Linear Algebra

compute.l1norm( arr )

Computes the L1 norm (Manhattan/Taxicab norm) of an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.l1norm( data ) );

compute.l2norm( arr )

Computes the L2 norm (Euclidean norm) of an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.l2norm( data ) );

compute.linfnorm( arr )

Computes the infinity norm (Chebyshev/maximum/supremum/uniform norm) of an array of values.

var data = [ 2, 4, 2, -7, 3 ];

console.log( compute.linfnorm( data ) );

compute.lpnorm( arr[, p] )

Computes the Lp norm of an array of values.

var data = [ 2, 4, 2, 7, 3 ];

// Compute the L5 norm:
console.log( compute.lpnorm( data, 5 ) );

Statistics

compute.min( arr )

Computes the minimum value of an array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.min( data ) );

compute.incrmin()

Returns a method to compute a minimum value incrementally.

var data = [ 2, 4, 2, 7, 3 ];

var min = incrmin(),
    m;

for ( var i = 0; i < data.length; i++ ) {
    m = min( data[ i ] );
    console.log( m );
}
console.log( min() );

compute.mmin( arr, window )

Computes a moving minimum over a numeric array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.mmin( data, 2 ) );

compute.max( arr )

Computes the maximum value of an array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.max( data ) );

compute.incrmax()

Returns a method to compute a maximum value incrementally.

var data = [ 2, 4, 2, 7, 3 ];

var max = incrmax(),
    m;

for ( var i = 0; i < data.length; i++ ) {
    m = max( data[ i ] );
    console.log( m );
}
console.log( max() );

compute.mmax( arr, window )

Computes a moving maximum over a numeric array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.mmax( data, 2 ) );

compute.range( arr )

Computes the arithmetic range of an array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.range( data ) );

compute.sum( arr )

Computes the sum of an array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.sum( data ) );

compute.nansum( arr )

Computes the sum of an array ignoring any non-numeric values.

var data = [ 2, NaN, 4, 2, 7, NaN, 3 ];

console.log( compute.nansum( data ) );

compute.incrsum()

Returns a method to compute a sum incrementally.

var data = [ 2, 4, 2, 7, 3 ];

var sum = incrsum(),
    s;

for ( var i = 0; i < data.length; i++ ) {
    s = sum( data[ i ] );
    console.log( s );
}
console.log( sum() );

compute.msum( arr, window )

Computes a moving sum over a numeric array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.msum( data, 2 ) );

compute.csum( arr )

Computes the cumulative sum of an array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.csum( data ) );

compute.mean( arr )

Computes the arithmetic mean over an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.mean( data ) );

compute.nanmean( arr )

Computes the arithmetic mean over an array of values ignoring any non-numeric values.

var data = [ 2, 4, NaN, 2, 7, NaN, 3 ];

console.log( compute.nanmean( data ) );

compute.incrmean()

Returns a method to compute an arithmetic mean incrementally.

var data = [ 2, 4, 2, 7, 3 ];

var mean = incrmean(),
    mu;

for ( var i = 0; i < data.length; i++ ) {
    mu = mean( data[ i ] );
    console.log( mu );
}
console.log( mean() );

compute.mmean( arr, window )

Computes a moving arithmetic mean (sliding window average) over a numeric array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.mmean( data, 2 ) );

compute.wmean( arr, weights )

Computes a weighted mean over an array of values.

var data = [ 2, 4, 2, 7, 3 ],
    weights = [ 1, 2, 1, 4, 0 ];

console.log( compute.wmean( data, weights ) );

compute.gmean( arr )

Computes the geometric mean over an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.gmean( data ) );

compute.nangmean( arr )

Computes the geometric mean over an array of values ignoring any non-numeric values.

var data = [ 2, 4, NaN, 2, 7, NaN, 3 ];

console.log( compute.nangmean( data ) );

compute.hmean( arr )

Computes the harmonic mean over an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.hmean( data ) );

compute.nanhmean( arr )

Computes the harmonic mean over an array of values ignoring any non-numeric values.

var data = [ 2, 4, NaN, 2, 7, NaN, 3 ];

console.log( compute.nanhmean( data ) );

compute.qmean( arr )

Computes the quadratic mean (root mean square) over an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.qmean( data ) );

compute.nanqmean( arr )

Computes the quadratic mean (root mean square) over an array of values ignoring any non-numeric values.

var data = [ 2, 4, NaN, 2, 7, NaN, 3 ];

console.log( compute.nanqmean( data ) );

compute.variance( arr )

Computes the sample variance over an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.variance( data ) );

compute.nanvariance( arr )

Computes the sample variance over an array of values ignoring any non-numeric values.

var data = [ 2, 4, NaN, 2, 7, NaN, 3 ];

console.log( compute.nanvariance( data ) );

compute.incrvariance()

Returns a method to compute a sample variance incrementally.

var data = [ 2, 4, 2, 7, 3 ];

var variance = incrvariance(),
    s2;

for ( var i = 0; i < data.length; i++ ) {
    s2 = variance( data[ i ] );
    console.log( s2 );
}
console.log( variance() );

compute.stdev( arr )

Computes the sample standard deviation over an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.stdev( data ) );

compute.nanstdev( arr )

Computes the sample standard deviation over an array of values ignoring any non-numeric values.

var data = [ 2, 4, NaN, 2, 7, NaN, 3 ];

console.log( compute.nanstdev( data ) );

compute.incrstdev()

Returns a method to compute a sample standard deviation incrementally.

var data = [ 2, 4, 2, 7, 3 ];

var stdev = incrstdev(),
    sigma;

for ( var i = 0; i < data.length; i++ ) {
    sigma = stdev( data[ i ] );
    console.log( sigma );
}
console.log( stdev() );

compute.mode( arr )

Computes the mode of an array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.mode( data ) );

compute.median( arr[, sorted] )

Computes the median of an array.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.median( data ) );

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

compute.quantile( arr, p[, opts] )

Computes a quantile for an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.quantile( data, 0.25 ) );

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

var opts = {
    'sorted': true
};

var data = [ 2, 2, 3, 4, 7 ];

console.log( compute.quantile( data, 0.25, opts ) );

compute.quantiles( arr, num[, opts] )

Computes quantiles for an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.quantiles( data, 3 ) );

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

var opts = {
    'sorted': true
};

var data = [ 2, 2, 3, 4, 7 ];

console.log( compute.quantiles( data, 2, opts ) );

compute.iqr( arr[, opts] )

Computes the interquartile range for an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.iqr( data ) );

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

compute.idr( arr[, opts] )

Computes the interdecile range for an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.idr( data ) );

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

compute.skewness( arr )

Computes the sample skewness of an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.skewness( data ) );

compute.kurtosis( arr )

Computes the sample excess kurtosis of an array of values.

var data = [ 2, 4, 2, 7, 3 ];

console.log( compute.kurtosis( data ) );

Geometry

compute.hypot( a, b )

Computes the hypotenuse of a right triangle.

var a = 10,
    b = 12;

console.log( compute.hypot( a, b ) );

Information Theory

compute.hamdist( a, b )

Computes the Hamming distance between two sequences of equal length.

var a = 'beep',
    b = 'boop';

console.log( compute.hamdist( a, b ) );

var c = [ 4, 2, 3, 4 ],
    d = [ 2, 4, 3, 1 ];

console.log( compute.hamdist( c, d ) );

Fluent Interface

For data pipelines, invoking serial methods can become verbose.

data = compute.roundn( data, -3 );
data = compute.mean( data );
data = compute.roundn( data, 0 );
...

Fluent interfaces can help alleviate this problem. Such interfaces have been popularized by libraries such as jQuery and D3 which utilize method chaining.

To create a fluent interface,

var flow = compute.flow();

A flow pipeline should be initialized.

flow.value( data );

Once initialized, all compute methods are now available. The lone difference is that data should not be explicitly passed as an argument. For example,

flow
    .value( data )
    .roundn( -3 )
    .mean()
    .roundn( 0 );

To return the flow value,

var mean = flow.value();

To help understand the transformations comprising a data pipeline, flow exposes an inspect() method, which logs the current value to the console while maintaining the fluent interface.

flow.inspect();

The above flow can be modified accordingly,

flow
    .value( data )
    .inspect()
    .roundn( -3 )
    .inspect()
    .mean()
    .inspect()
    .roundn( 0 )
    .inspect();

To summarize the flow API...

flow.value( [value] )

This method is a setter/getter. If no value is provided, returns the current flow value. If a value is provided, sets the flow value.

flow.value( [ 4, 3, 6, 2 ] );

flow.inspect()

Logs the current flow value to the console, while maintaining the fluent interface.

flow.inspect();

Notes

When creating flows, ensure that the output from one computation matches the input argument requirements for the next computation.

For large datasets, rather than loading datasets into memory, consider using file streams and utilize stream tools such as [Flow.io](https://github.com/flow-io/flow.io).

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.

compute.io