@punkeel/random

random

Seedable random number generator supporting many common distributions.

Welcome to the most random module on npm! 😜

Highlights

• Simple API (make easy things easy and hard things possible)
• Seedable based on entropy or user input
• Plugin support for different pseudo random number generators (PRNGs)
• Sample from many common distributions
  • uniform, normal, poisson, bernoulli, etc
• Validates all user input via ow
• Integrates with seedrandom
• Supports node >= 6 and browser

Install

npm install --save random

Usage

const random = require('random')

// quick uniform shortcuts
random.float(min = 0, max = 1) // uniform float in [ min, max )
random.int(min = 0, max = 1) // uniform integer in [ min, max ]
random.boolean() // true or false

// uniform
random.uniform(min = 0, max = 1) // () => [ min, max )
random.uniformInt(min = 0, max = 1) // () => [ min, max ]
random.uniformBoolean() // () => [ false, true ]

// normal
random.normal(mu = 0, sigma = 1)
random.logNormal(mu = 0, sigma = 1)

// bernoulli
random.bernoulli(p = 0.5)
random.binomial(n = 1, p = 0.5)
random.geometric(p = 0.5)

// poisson
random.poisson(lambda = 1)
random.exponential(lambda = 1)

// misc
random.irwinHall(n)
random.bates(n)
random.pareto(alpha)

For convenience, several common uniform samplers are exposed directly:

random.float()     // 0.2149383367670885
random.int(0, 100) // 72
random.boolean()   // true

All distribution methods return a thunk (function with no params), which will return a series of independent, identically distributed random variables from the specified distribution.

// create a normal distribution with default params (mu=1 and sigma=0)
const normal = random.normal()
normal() // 0.4855465422678824
normal() // -0.06696771815439678
normal() // 0.7350852689834705

// create a poisson distribution with default params (lambda=1)
const poisson = random.poisson()
poisson() // 0
poisson() // 4
poisson() // 1

Note that returning a thunk here is more efficient when generating multiple samples from the same distribution.

You can change the underlying PRNG or its seed as follows:

const seedrandom = require('seedrandom')

// change the underlying pseudo random number generator
// by default, Math.random is used as the underlying PRNG
random.use(seedrandom('foobar'))

// create a new independent random number generator (uses seedrandom under the hood)
const rng = random.clone('my-new-seed')

// create a second independent random number generator and use a seeded PRNG
const rng2 = random.clone(seedrandom('kittyfoo'))

// replace Math.random with rng.uniform
rng.patch()

// restore original Math.random
rng.unpatch()

API

Table of Contents

• Random
  • rng
  • clone
  • use
  • patch
  • unpatch
  • next
  • float
  • int
  • integer
  • bool
  • boolean
  • uniform
  • uniformInt
  • uniformBoolean
  • normal
  • logNormal
  • bernoulli
  • binomial
  • geometric
  • poisson
  • exponential
  • irwinHall
  • bates
  • pareto

Random

Seedable random number generator supporting many common distributions.

Defaults to Math.random as its underlying pseudorandom number generator.

Type: function (rng)

• rng (RNG | function) Underlying pseudorandom number generator. (optional, default Math.random)

---

rng

Type: function ()

---

clone

• See: RNG.clone

Creates a new Random instance, optionally specifying parameters to set a new seed.

Type: function (args, seed, opts): Random

• args ...any
• seed string? Optional seed for new RNG.
• opts object? Optional config for new RNG options.

---

use

Sets the underlying pseudorandom number generator used via either an instance of seedrandom, a custom instance of RNG (for PRNG plugins), or a string specifying the PRNG to use along with an optional seed and opts to initialize the RNG.

Type: function (args)

• args ...any

Example:

const random = require('random')

random.use('example_seedrandom_string')
// or
random.use(seedrandom('kittens'))
// or
random.use(Math.random)

---

patch

Patches Math.random with this Random instance's PRNG.

Type: function ()

---

unpatch

Restores a previously patched Math.random to its original value.

Type: function ()

---

next

Convenience wrapper around this.rng.next()

Returns a floating point number in [0, 1).

Type: function (): number

---

float

Samples a uniform random floating point number, optionally specifying lower and upper bounds.

Convence wrapper around random.uniform()

Type: function (min, max): number

• min number Lower bound (float, inclusive) (optional, default 0)
• max number Upper bound (float, exclusive) (optional, default 1)

---

int

Samples a uniform random integer, optionally specifying lower and upper bounds.

Convence wrapper around random.uniformInt()

Type: function (min, max): number

• min number Lower bound (integer, inclusive) (optional, default 0)
• max number Upper bound (integer, inclusive) (optional, default 1)

---

integer

Samples a uniform random integer, optionally specifying lower and upper bounds.

Convence wrapper around random.uniformInt()

Type: function (min, max): number

• min number Lower bound (integer, inclusive) (optional, default 0)
• max number Upper bound (integer, inclusive) (optional, default 1)

---

bool

Samples a uniform random boolean value.

Convence wrapper around random.uniformBoolean()

Type: function (): boolean

---

boolean

Samples a uniform random boolean value.

Convence wrapper around random.uniformBoolean()

Type: function (): boolean

---

uniform

Generates a Continuous uniform distribution.

Type: function (min, max): function

• min number Lower bound (float, inclusive) (optional, default 0)
• max number Upper bound (float, exclusive) (optional, default 1)

---

uniformInt

Generates a Discrete uniform distribution.

Type: function (min, max): function

• min number Lower bound (integer, inclusive) (optional, default 0)
• max number Upper bound (integer, inclusive) (optional, default 1)

---

uniformBoolean

Generates a Discrete uniform distribution, with two possible outcomes, true or `false.

This method is analogous to flipping a coin.

Type: function (): function

---

normal

Generates a Normal distribution.

Type: function (mu, sigma): function

• mu number Mean (optional, default 0)
• sigma number Standard deviation (optional, default 1)

---

logNormal

Generates a Log-normal distribution.

Type: function (mu, sigma): function

• mu number Mean of underlying normal distribution (optional, default 0)
• sigma number Standard deviation of underlying normal distribution (optional, default 1)

---

bernoulli

Generates a Bernoulli distribution.

Type: function (p): function

• p number Success probability of each trial. (optional, default 0.5)

---

binomial

Generates a Binomial distribution.

Type: function (n, p): function

• n number Number of trials. (optional, default 1)
• p number Success probability of each trial. (optional, default 0.5)

---

geometric

Generates a Geometric distribution.

Type: function (p): function

• p number Success probability of each trial. (optional, default 0.5)

---

poisson

Generates a Poisson distribution.

Type: function (lambda): function

• lambda number Mean (lambda > 0) (optional, default 1)

---

exponential

Generates an Exponential distribution.

Type: function (lambda): function

• lambda number Inverse mean (lambda > 0) (optional, default 1)

---

irwinHall

Generates an Irwin Hall distribution.

Type: function (n): function

• n number Number of uniform samples to sum (n >= 0) (optional, default 1)

---

bates

Generates a Bates distribution.

Type: function (n): function

• n number Number of uniform samples to average (n >= 1) (optional, default 1)

---

pareto

Generates a Pareto distribution.

Type: function (alpha): function

• alpha number Alpha (optional, default 1)

---

Todo

• Distributions

  • [x] uniform
  • [x] uniformInt
  • [x] uniformBoolean
  • [x] normal
  • [x] logNormal
  • [ ] chiSquared
  • [ ] cauchy
  • [ ] fischerF
  • [ ] studentT
  • [x] bernoulli
  • [x] binomial
  • [ ] negativeBinomial
  • [x] geometric
  • [x] poisson
  • [x] exponential
  • [ ] gamma
  • [ ] hyperExponential
  • [ ] weibull
  • [ ] beta
  • [ ] laplace
  • [x] irwinHall
  • [x] bates
  • [x] pareto

• Generators

  • [x] pluggable prng
  • [ ] port more prng from boost
  • [ ] custom entropy

• Misc

  • [x] browser support via rollup
  • [x] basic docs
  • [x] basic tests
  • [x] test suite
  • [x] initial release!

Related

• d3-random - D3's excellent random number generation library.
• seedrandom - Seedable pseudo random number generator.
• random-int - For the common use case of generating uniform random ints.
• random-float - For the common use case of generating uniform random floats.
• randombytes - Random crypto bytes for Node.js and the browser.

Credit

Huge shoutout to Roger Combs for donating the random npm package for this project!

Lots of inspiration from d3-random (@mbostock and @svanschooten).

Some distributions and PRNGs are ported from C++ boost::random.

License

MIT © Travis Fischer