compute-variance

    3.0.0 • Public • Published

    Variance

    NPM version Build Status Coverage Status Dependencies

    Computes the variance.

    The population variance (biased sample variance) is defined as

    Equation for the population (biased sample) variance.

    and the unbiased sample variance is defined as

    Equation for the unbiased sample variance.

    where x_0, x_1,...,x_{N-1} are individual data values and N is the total number of values in the data set.

    Installation

    $ npm install compute-variance

    For use in the browser, use browserify.

    Usage

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

    variance( x[, opts] )

    Computes the variance. x may be either an array, typed array, or matrix.

    var data, s2;
     
    data = [ 2, 4, 5, 3, 4, 3, 1, 5, 6, 9 ];
    s2 = variance( data );
    // returns 5.067
     
    data = new Int8Array( data );
    s2 = variance( data );
    // returns 5.067

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

    var data = [
        {'x':2},
        {'x':4},
        {'x':5},
        {'x':3},
        {'x':4},
        {'x':3},
        {'x':1},
        {'x':5},
        {'x':6},
        {'x':9}
    ];
     
    function getValue( d ) {
        return d.x;
    }
     
    var s2 = variance( data, {
        'accessor': getValue
    });
    // returns 5.067

    By default, the function calculates the unbiased sample variance. To calculate the population variance (or a biased sample variance), set the bias option to true.

    var data = [ 2, 4, 5, 3, 4, 3, 1, 5, 6, 9 ];
     
    var sigma2 = variance( data, {
        'bias': true
    });
    // returns 4.56

    If provided a matrix, the function accepts the following additional options:

    • dim: dimension along which to compute the variance. Default: 2 (along the columns).
    • dtype: output matrix data type. Default: float64.

    By default, the function computes the variance along the columns (dim=2).

    var matrix = require( 'dstructs-matrix' ),
        data,
        mat,
        s2,
        i;
     
    data = new Int8Array( 25 );
    for ( i = 0; i < data.length; i++ ) {
        data[ i ] = i;
    }
    mat = matrix( data, [5,5], 'int8' );
    /*
        [  0  1  2  3  4
           5  6  7  8  9
          10 11 12 13 14
          15 16 17 18 19
          20 21 22 23 24 ]
    */
     
    s2 = variance( mat );
    /*
        [  2.5
           2.5
           2.5
           2.5
           2.5 ]
    */

    To compute the variance along the rows, set the dim option to 1.

    s2 = variance( mat, {
        'dim': 1
    });
    /*
        [ 62.5, 62.5, 62.5, 62.5, 62.5 ]
    */

    By default, the output matrix data type is float64. To specify a different output data type, set the dtype option.

    s2 = variance( mat, {
        'dim': 1,
        'dtype': 'uint8'
    });
    /*
        [ 62.5, 62.5, 62.5, 62.5, 62.5 ]
    */
     
    var dtype = s2.dtype;
    // returns 'uint8'

    If provided a matrix having either dimension equal to 1, the function treats the matrix as a typed array and returns a numeric value.

    data = [ 2, 4, 5, 3, 4, 3, 1, 5, 6, 9  ];
     
    // Row vector:
    mat = matrix( new Int8Array( data ), [1,10], 'int8' );
    s2 = variance( mat );
    // returns 5.067
     
    // Column vector:
    mat = matrix( new Int8Array( data ), [10,1], 'int8' );
    s2 = variance( mat );
    // returns 5.067

    If provided an empty array, typed array, or matrix, the function returns null.

    s2 = variance( [] );
    // returns null
     
    s2 = variance( new Int8Array( [] ) );
    // returns null
     
    s2 = variance( matrix( [0,0] ) );
    // returns null
     
    s2 = variance( matrix( [0,10] ) );
    // returns null
     
    s2 = variance( matrix( [10,0] ) );
    // returns null

    Examples

    var matrix = require( 'dstructs-matrix' ),
        variance = require( 'compute-variance' );
     
    var data,
        mat,
        s2,
        i;
     
    // Plain arrays...
    var data = new Array( 100 );
    for ( var i = 0; i < data.length; i++ ) {
        data[ i ] = Math.round( Math.random() * 10 + 1 );
    }
    s2 = variance( data );
     
    // Object arrays (accessors)...
    function getValue( d ) {
        return d.x;
    }
    for ( i = 0; i < data.length; i++ ) {
        data[ i ] = {
            'x': data[ i ]
        };
    }
    s2 = variance( data, {
        'accessor': getValue
    });
     
    // Typed arrays...
    data = new Int32Array( 100 );
    for ( i = 0; i < data.length; i++ ) {
        data[ i ] = Math.round( Math.random() * 10 + 1 );
    }
    s2 = variance( data );
     
    // Matrices (along rows)...
    mat = matrix( data, [10,10], 'int32' );
    s2 = variance( mat, {
        'dim': 1
    });
     
    // Matrices (along columns)...
    s2 = variance( mat, {
        'dim': 2
    });
     
    // Matrices (custom output data type)...
    s2 = variance( mat, {
        'dtype': 'uint8'
    });

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

    Install

    npm i compute-variance

    DownloadsWeekly Downloads

    473

    Version

    3.0.0

    License

    MIT

    Last publish

    Collaborators

    • kgryte
    • planeshifter