Gauss

JavaScript statistics, analytics, and set library - Node.js and web browser ready

Evented, asynchronous, and fast, Node.js is an attractive platform for data mining, statistics, and data analysis. Gauss makes it easy to calculate and explore data through JavaScript, both on Node.js and within the web browser.

License

MIT/X11 - See LICENSE

Support

Mailing list - Google Group

Getting started

Install with NPM (Node Package Manager)

Getting started with Gauss + Node.js is easy:

$ npm install gauss

var gauss = require('gauss');

Using Gauss within a web browser

Gauss requires support for ECMAScript 5 Object.defineProperty. Compatibility is listed here. Download and include gauss.min.js:

<script src="gauss.min.js" type="text/javascript"></script>
<script type="text/javascript" charset="utf-8">
    var Vector = gauss.Vector,
        TimeSeries = gauss.TimeSeries;
    var set = new gauss.Vector(5, 1, 3, 2, 21),
        numbers = new Vector([8, 6, 7, 5, 3, 0, 9]);
</script>

The Bower package manager can also be used to install Gauss:

$ bower install gauss

Gauss is also Asynchronous Module Definition compatible and works with module loaders like RequireJS:

<script async src="gauss.min.js"></script>
<script>
    require(['gauss'], function(gauss) {
        var Collection = gauss.Collection,
            distribution = new Collection(1, 2, 3).distribution();
    });
</script>

Installing development dependencies and running tests

To run Gauss's tests you'll need Vows. NPM can automatically resolve this:

$ npm install gauss --devel

To invoke the tests:

$ npm test

API

Instantiation

// List of numbers
var set = new gauss.Vector(5, 1, 3, 2, 21);
// From a regular Array
var numbers = new gauss.Vector([8, 6, 7, 5, 3, 0, 9]);
// After instantiation, Gauss objects can be conveniently used like any Array
numbers[0] = 2;
set[1] = 7;

Note: To prevent unintended scope/prototype pollution, Gauss versions after 0.2.3 have removed support for monkey patching the native Array data type. Use the .toArray() method of any Gauss object to a convert to a vanilla Array.

Scope chaining

Gauss collections utilize scope chaining for converting between collection types:

var Collection = gauss.Collection;
var things = new Collection(
    { type: 1, age: 1 },
    { type: 2, age: 2 },
    { type: 1, age: 3 },
    { type: 2, age: 4 });
things
    .find({ type: 2 })
    .map(function(thing) { return thing.age; })
    .toVector() // Scope chained converter, converting mapped collection of ages to Vector
    .sum();

Callbacks and method chaining

All of Gauss's methods accept an optional callback:

set.min();
set.min(function(result) {
    result / 2;
    /* Do more things with the minimum*/
});

In addition, for methods that return another Vector, method chaining makes it easy to perform calculations that flow through each other:

set.quantile(4).stdev(); // Find the standard deviation of data set's quartiles

Finally, you can mix and match both callbacks and chaining:

set.quantile(4).stdev(function(stdev) {
    if (stdev > 1) {
        /* Do something awesome */
    }
});

Collection

Collection.indexBy

.indexBy(predicate, callback)

Returns the first index of an element that matches a condition.

Collection.indicesOf

.indicesOf(element, callback)

Returns the indices of all elements that match a value.

Collection.indicesBy

.indicesBy(predicate, callback)

Returns all indices of an element that match a condition.

Collection.lastIndexBy

.lastIndexBy(predicate, callback)

Returns the last index of an element that matches a condition.

Collection.find

.find(predicate, callback)

Returns all the elements that match a condition.

var people = new gauss.Collection(
  { firstname: 'John', lastname: 'Smith' },
  { firstname: 'Jane', lastname: 'Doe' },
  { firstname: 'Mike', lastname: 'Smith' },
  { firstname: 'Susan', lastname: 'Baker' }
);
// Using a predicate Function
people.find(function(e) { return e.firstname === 'Jane' });
> [{ firstname: 'Jane', lastname: 'Doe' }]
// Using a condition Object
people.find({ lastname: 'Smith' });
> [{ firstname: 'John', lastname: 'Smith' },
  { firstname: 'Mike', lastname: 'Smith' }]

Collection.findOne

.findOne(predicate, callback)

Returns the first element that matches a condition.

// Using a predicate Function
people.findOne(function(e) { return e.firstname === 'Jane' });
> { firstname: 'Jane', lastname: 'Doe' }
// Using a condition Object
people.findOne({ lastname: 'Smith' });
> { firstname: 'John', lastname: 'Smith' }

Collection.split

.split(predicate[, callback])

Returns a Collection split by a condition (binomial cluster).

Collection(1, 2, 3, 4).split(function(e) { return e % 2 === 0 });
> [[1, 3], [2, 4]]

Collection.mode

.mode(callback)

Returns the value(s) that occur the most frequently in a data set. If there is a tie, returns a Collection of values.

Collection.frequency

.frequency(element, callback)

Returns the number of occurrences of value within a data set.

Collection.distribution

.distribution(format, callback)

Returns an Object containing the (frequency) distribution of values within the Collection. Default format: absolute; relative returns ratio of occurrences and total number of values in a data set.

set.distribution();
> {
    1: 1,
    2: 1,
    3: 1,
    5: 1,
    21: 1
  }
set.distribution('relative');
> {
    1: 0.2,
    2: 0.2,
    3: 0.2,
    5: 0.2,
    21: 0.2
  }

Collection.append

.append(that, callback)

Return Collection appended with an Array.

var numbers = new Collection(1, 2, 3).append([1, 2, 3]);
> [1, 2, 3, 1, 2, 3]

Collection.unique

.unique(callback)

Return a Collection with unique values.

var numbers = new Collection(1, 2, 3, 3, 4, 4).unique();
> [1, 2, 3, 4]

Collection.union

.union(array, callback)

Return the union of a Collection with another array.

var union = new Collection('a', 'b', 'c').union(['c', 'd', 'e']);
> ['a', 'b', 'c', 'd', 'e']

Collection.extend

.extend(methods, callback)

Returns a Collection extended with named functions.

Vector

Extends Collection methods with numerical functions.

Vector.min

.min(callback)

Returns the smallest number.

Vector.max

.max(callback)

Returns the largest number.

Vector.equal

.equal(that)

Returns true or false if Vector values are equal to another Vector or Array.

Vector.sum

.sum(callback)

Returns the sum of the numbers.

Vector.product

.product(callback)

Returns the product of the numbers.

Vector.push

.push(number1, ..., numberN, callback)

Returns the updated Vector with one or more elements appended to the end; performs/maintains streaming calculations.

var Vector = require('gauss').Vector,
    digits = new Vector();
// Push some numbers in
digits.push(1, 2, 3);
> 3
digits.sum();
> 6
// Keep on pushing; sum is updated as numbers are pushed
 digits.push(4, 5, 6);
> 6

Note: Streaming calculations like sum(), product(), variance(), and functions dependent on streaming capable functions benefit from O(1) amortized performance.

Vector.range

.range(callback)

Returns the difference between the largest and smallest value in a data set.

Vector.mean

.mean(callback)

Returns the arithmetic mean.

Vector.gmean

.gmean(callback)

Returns the geometric mean.

Vector.hmean

.hmean(callback)

Returns the harmonic mean.

Vector.qmean

.qmean(callback)

Returns the quadratic mean (RMS, root mean square).

Vector.pmean

.pmean(p, callback)

Returns the power/generalized mean given an order or power p.

// p = -1, harmonic mean
set.pmean(-1);
// p = 1, arithmetic mean
set.pmean(1);
// p = 2, quadratic mean
set.pmean(2);

Vector.median

.median(callback)

Returns the median. If there are an even amount of numbers in the data set, returns the arithmetic mean of the two middle values.

Vector.mode

.mode(callback)

Returns the value(s) that occur the most frequently in a data set. If there is a tie, returns a Vector of values.

Vector.variance

.variance(callback)

Returns a measure of how far a set of numbers are spread out from each other.

Vector.stdev

.stdev(percent, callback)

Returns the standard deviation of data set. If a percent is given, returns the standard deviation with respect to a percentile of the population.

Vector.frequency

.frequency(value, callback)

Returns the number of occurrences of value within a data set.

Vector.percentile

.percentile(value, callback)

Returns the value that below which a certain percent of observations fall within the data set.

Vector.density

.density(percent