# trials

Statistical trials to generate simple outcomes

``npm install trials``

# Trials

Trials is a small library for generating outcomes conforming to simple statistical rules by running repeated trials in these systems.

It can pick from a probability mass function (pmf), do repeated Bernoulli trials for elements in an array, unique Bernoulli trials for every element of an object of `key` : `probability` form and more.

## Usage

Require and call one of the functions within.

``````var t = require('trials');
for (var i = 0; i < 10; i += 1) {
// collect results of 10 trials where we pick exactly one of the object below
t.singlePmf({
attack: 0.6,
runaway: 0.3,
eatlunch: 0.1
};
}
``````

Outputs something like this:

``````runaway
attack
attack
eatlunch
attack
attack
runaway
eatlunch
attack
attack
``````

Results vary based on rolls - this one had more lunches than an average roll.

## API

### singlePmf(obj)

Takes an object of form `key` : `probability` (which acts as the probability mass function for all the keys in the object) and picks exactly one element according the a roll mapped to the mass function. The introduction above has an example of this.

An important thing to note with this function is that the values of the object must sum to 1 for it to represent a proper mass function (and to guarantee a return value).

### single(ary)

Takes an Array and picks exactly one element from the array with uniform probability.

``````for (var i = 0; i < 5; i += 1) t.single(['hi', 'thar', 'miss']);
``````

Example output:

``````hi
miss
thar
miss
thar
``````

### multipleProbs(obj)

Takes an object of individual probabilities, does one Bernoulli trial for each element of the object with the respective probabilities and collects all the keys of the successes.

``````for (var i = 0; i < 5; i += 1) {
t.multipleProbs({
a: 0.4,
b: 0.4,
c: 0.1
});
}
``````

Example output:

``````[ 'b' ]
[ 'a', 'b' ]
[ 'b' ]
[]
[ 'a', 'b' ]
``````

### multiple(ary, p)

Takes an array and a fixed probability, does one Bernoulli trial for each element in the array with the defined uniform probability, and collects all the successes.

``````for (var i = 0; i < 5; i += 1) t.multiple(['a', 'b', 'c'], 0.4);
``````

Example output:

``````[ 'a' ]
[ 'a', 'b', 'c' ]
[]
[ 'b', 'c' ]
[ 'b' ]
``````

### range(start, end)

Gets an integer in the range `start` to (and including) `end` with uniform probability. Equivalent to `single` on the array `[start, start+1, ... , end]`, but more efficient.

### cluster(ary, max, p)

Cluster picks {1, 2, ..., max} elements uniformly from the array with probability `p`, or it picks none at all with probability `1-p`.

This is essentially a uniform distribution within a uniform distribution. It's uniform in that we either pick or don't pick with probability `p`, and if we pick, then how many we pick is uniformly distributed in the defined range. This creates the clusters, rather than true randomness.

``````for (var i = 0; i < 5; i += 1) t.cluster([1, 2, 3, 4, 5], 3, 0.6);
``````

Example output:

``````[ 2, 1 ]
[ 4, 1, 5 ]
[ 1 ]
[]
[ 3, 1, 4 ]
[ 2 ]
``````

## Installation

``````\$ npm install trials
``````

## Running tests

Install development dependencies

``````\$ npm install
``````

Run the tests

``````\$ npm test
``````