tabulateBy

    Generate a frequency table according to an indicator function.

    Usage

    var tabulateBy = require( '@stdlib/utils/tabulate-by' );
    

    tabulateBy( collection[, options,] indicator )

    Generates a frequency table according to an indicator function, i.e., a function which specifies how to categorize an element in the input collection.

    function indicator( v ) {
        return v[ 0 ];
    }
    var arr = [ 'beep', 'boop', 'foo', 'beep' ];
    
    var out = tabulateBy( arr, indicator );
    // returns [ [ 'b', 3, 0.75 ], [ 'f', 1, 0.25 ] ]
    

    An indicator function is provided two arguments:

    • value: collection element
    • index: collection index
    function indicator( v, i ) {
        console.log( '%d: %s', i, v );
        return v[ 0 ];
    }
    var arr = [ 'beep', 'boop', 'foo', 'bar' ];
    
    var out = tabulateBy( arr, indicator );
    // returns [ [ 'b', 3, 0.75 ], [ 'f', 1, 0.25 ] ]
    

    The function accepts the following options:

    • thisArg: execution context.

    To set the indicator execution context, provide a thisArg.

    function indicator( v ) {
        this.count += 1;
        return v[ 0 ];
    }
    var context = {
        'count': 0
    };
    var opts = {
        'thisArg': context
    };
    var arr = [ 'beep', 'boop', 'foo', 'bar' ];
    
    var out = tabulateBy( arr, opts, indicator );
    // returns [ [ 'b', 3, 0.75 ], [ 'f', 1, 0.25 ] ]
    
    console.log( context.count );
    // => 4
    

    The returned frequency table is an array of arrays. Each sub-array corresponds to a unique value in the input collection and is structured as follows:

    • 0: unique value
    • 1: value count
    • 2: frequency percentage

    Notes

    • A collection may be either an Array, Typed Array, or an array-like Object (excluding strings and functions).

    Examples

    var randu = require( '@stdlib/random/base/randu' );
    var floor = require( '@stdlib/math/base/special/floor' );
    var tabulateBy = require( '@stdlib/utils/tabulate-by' );
    
    var vals;
    var arr;
    var out;
    var i;
    var j;
    
    function indicator( value ) {
        return value[ 0 ];
    }
    
    vals = [ 'beep', 'boop', 'foo', 'bar', 'woot', 'woot' ];
    
    // Generate a random collection...
    arr = new Array( 100 );
    for ( i = 0; i < arr.length; i++ ) {
        j = floor( randu()*vals.length );
        arr[ i ] = vals[ j ];
    }
    
    // Generate a frequency table:
    out = tabulateBy( arr, indicator );
    console.log( out );