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
• Functions

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.

• Normal Distribution Functions
  • choose
  • mean
  • range
• Uniform Distribution Functions
  • choose
  • range
• Custom Distribution Functions
  • choose
  • 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)