randtools

**randtools**is a small JavaScript library to generate random numbers and select random elements from arrays. It supports normal distributions as well as uniform) and custom distributions.

## Installation

**randtools**is available as an npm package. Simply run:

`$ npm install randtools`

Then you can require and use it like any other module.

```
const rnd = require('randtools')
//Generate a random number with a normal distribution with a mean of 100 and a standard deviation of 10
const normalDistNum = rnd.normal.mean(100, 10)
//Generate a random two-decimal number with a uniform distribution ranging from 2 to 3
const decimalNum = rnd.uniform.range(2, 3, 2)
```

## New API

**randtools**offers a total of seven functions for three different kinds of distributions.

```
- [choose](#normal-choose)
- [mean](#normal-mean)
- [range](#normal-range)
```

```
- [choose](#uniform-choose)
- [range](#uniform-range)
```

```
- [choose](#custom-choose)
- [sequence](#custom-sequence)
```

### Normal Distribution Functions

These functions are based on the Box-Muller transform to generate a random number with a normal distribution. They will generate a random result that tends towards the mean.#### choose(array, deviations) {#normal-choose}

Returns a random element from a given array.`array`

: the array from which to choose an element.`deviations`

: the amount of standard deviations within the allowed range of results. A small number will create a more uniform distribution, while a number greater than 4 will cause the chances of the elements at the beginning and end of the array to be negligible. It defaults to three. It won't accept any value smaller than 1.

```
const list = [ 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h' ]
rnd.normal.choose(list, 1) //Distribution will be closer to uniform
rnd.normal.choose(list, 4) //Distribution will lean very heavily toward 'e' and 'f'
```

#### mean(mean, deviation, decimals) {#normal-mean}

Generates a random number.`mean`

: the mean of the distribution. The generated numbers will tend towards this value.`deviation`

: the standard deviation of the distribution. The greater it is, the greater the variance will be.`decimals`

: the amount of decimals that the generated number will have. It defaults to zero.

```
rnd.normal.mean(10, 2)
rnd.normal.mean(100, 20, 1)
```

#### range(from, to, decimals, devs) {#normal-range}

Generates a random number within a given range.`from`

: the smallest possible returned number.`to`

: the lagest possible returned number.`decimals`

: the amount of decimals that the generated number will have. It defauls to zero. If either`from`

or`to`

is a number with more decimal digits than`decimals`

, the function will use that amount instead.`devs`

: the amount of standard deviations within the allowed range of results. A small number will create a more uniform distribution, while a big number will reduce the chances of numbers on the fringes of the range to come up. It defaults to three. It won't accept any value smaller than 1.

The following code will return a random number from an approximately normal distribution with a mean of 10 and a standard deviation of 2, but always within the range 4-16:

`rnd.normal.range(4, 16)`

### Uniform Distribution Functions

These functions will generate a random result with a uniform distribution) in which all possible results are equally likely.#### choose(array) {#uniform-choose}

Returns a random element from a given array.`array`

: the array from which to choose an element.

```
const list = [ 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h' ]
rnd.uniform.choose(list) //Same probabilities for all elements
```

#### range(from, to, decimals) {#uniform-range}

Generates a random number within a given range.`from`

: the smallest possible returned number.`to`

: the largest possible returned number.`decimals`

: the amount of decimals that the generated number will have. It defaults to zero. If either`from`

or`to`

is a number with more decimal digits than`decimals`

, the function will use that amount instead.

```
rnd.uniform.range(1, 10)
rnd.uniform.range(2.5, 3.5)
rnd.uniform.range(2.5, 3.5, 2)
```

### Custom Distribution Functions

These functions allow the user to set a custom distribution and define the likeliness for each result to be returned.#### choose(array, chance) {#custom-choose}

Returns a random element from a given array.`array`

: the array from which to choose an element.`chance`

: an array in which the cumulative chance for each element of`array`

is given. The last element should be given a value of`100`

.

This function takes two arrays of the same length. The first one are the values from which to return something. The second one describes how likely each result is to come up. In the following code,

`cstmChoose`

will return an element from `array`

. `a`

will have a 20% to be returned, `b`

's chance will be 30% (50 - 20) and `c`

's 50% (100 - 50).```
const array = [ "a", "b", "c" ]
const likelihood = [ 20, 50, 100 ]
const randElem = rnd.custom.choose(array, likelihood)
```

**Note**that if

`array`

is longer than `chance`

, the elements with higher indexes will never be returned. Conversely, if `chance`

is longer or if the last element is below 100, the function might return `undefined`

.#### sequence(start, chance, options ) {#custom-sequence}

Returns a random number from a sequence defined by a starting point and, optionally, a step.`start`

: the starting point of the sequence.`chance`

: an array in which the cumulative chance for each number of the sequence is given. The last element should be given a value of`100`

.`options`

: an optional object with the key`step`

, which indicates how much the numbers of the sequence should increase in each step. It defaults to`1`

.

The function will return a random element in a sequence of the same length as the

`chance`

array.```
const chances = [ 15, 25, 40, 50, 85, 100 ]
rnd.custom.sequence(10, chances) //Returns a random number in the sequence [ 10, 11, 12, 13, 14, 15 ]
rnd.custom.sequence(0, chances, { step: 0.25 }) //Returns a random number in the sequence [ 0, 0.25, 0.5, 0.75, 1, 1.25 ]
```

## Old API

The old API has been preserved for now for compatibility reasons, but will be deleted in the future. So it is advisable to write new code using the new API.#### normal(mean, deviation, decimals)

Alias of normal.mean.`rnd.normal(10, 2)`

#### normChoose(array, devs)

Alias of normal.choose.```
const list = [ 'a', 'b', 'c', 'd', 'e', 'f' ]
rnd.normChoose(list, 2)
```

#### normRange(from, to, decimals, devs)

Alias of normal.range`rnd.normRange(1, 2, 1, 2)`

#### unifChoose(array)

Alias of uniform.choose`rnd.unifChoose([ 'a', 'b', 'c' ])`

#### unifRange(from, to, decimals)

Alias of uniform.range`rnd.unifRange(0, 18)`

#### cstmChoose(array, chance)

Alias of custom.choose```
const array = [ 'a', 'b', 'c' ]
const likelihood = [ 10, 30, 100 ]
rnd.cstmChoose(array, likelihood)
```