# 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.

Outputs something like this:

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.

Example output:

### 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.

Example output:

### 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.

Example output:

By virtue of being repeated, independent Bernoulli trials with constant probability; the number of picks from the array follows a Binomial distribution `B(ary.length, p)`.

### 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.

Example output: