random

> Seedable random number generator supporting many common distributions.

   

Welcome to the most random module on npm! 😜

Highlights

- Simple TS API with zero dependencies
- Seedable
- Plugin support for different pseudo random number generators
- Includes many common distributions
- uniform, normal, poisson, bernoulli, etc
- Replacement for seedrandom which hasn't been updated in over 5 years
- Supports all modern JS/TS runtimes

Install

``bash
npm install random
`

Usage

`ts
import random from '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 distribution
random.uniform((min = 0), (max = 1)) // () => [ min, max )
random.uniformInt((min = 0), (max = 1)) // () => [ min, max ]
random.uniformBoolean() // () => [ false, true ]

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

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

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

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

For convenience, several common uniform samplers are exposed directly:

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

// random array item
random.choice([1, true, 'foo']) // 'foo'

// sample multiple items without replacement
random.sample([1, true, 'foo'], 2) // [true, 'foo']

const dist = random.sampler([1, true, 'foo'], 2)
dist() // [true, 'foo']
dist() // ['foo', 1]
dist() // [1, true]

// shuffle arrays
random.shuffle([1, true, 'foo']) // ['foo', 1, true]

const dist = random.shuffler([1, true, 'foo'])
dist() // [true, 'foo', 1]
dist() // ['foo', true, 1]
dist() // [1, 'foo', 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.

`ts
// create a normal distribution with default params (mu=0 and sigma=1)
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:

`ts
// change the underlying pseudo random number generator seed.
// by default, Math.random is used as the underlying PRNG, but it is not seedable,
// so if a seed is given, we use an ARC4 PRNG (the same one used by seedrandom).
random.use('my-seed')

// create a new independent random number generator with a different seed
const rng = random.clone('my-new-seed')

// create a third independent random number generator using a custom PRNG
import seedrandom from 'seedrandom'
const rng2 = random.clone(seedrandom('kitty-seed'))
`

You can also instantiate a fresh instance of Random:

`ts
import { Random } from 'random'

const rng = new Random() // (uses Math.random)
const rng2 = new Random('my-seed-string')
const rng3 = new Random(() => {
/ custom PRNG / return Math.random()
})
`

API

#### Table of Contents

- Random
- rng
- clone
- use
- next
- float
- int
- integer
- bool
- boolean
- choice
- uniform
- uniformInt
- uniformBoolean
- normal
- logNormal
- bernoulli
- binomial
- geometric
- poisson
- exponential
- irwinHall
- bates
- pareto
- weibull

$3

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:

`javascript
import random from 'random'

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

---

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

---

#### choice

Returns an item chosen uniformly at random from the given array.

Convence wrapper around random.uniformInt()

Type: function choice (array: Array): T | undefined

- array Array Array of items to sample from

---

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

---

#### weibull

Generates a Weibull distribution.

Type: function (lambda, k): function

- lambda number lambda, the scale parameter (lambda > 0)
- k number k, the shape parameter (k > 0)

---

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
- [x] weibull
- [ ] beta
- [ ] laplace
- [x] irwinHall
- [x] bates
- [x] pareto

- Generators

- [x] pluggable prng
- [ ] port more prng from boost / seedrandom

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.
- jshash prngs

Credit

Thanks go to Andrew Moss for the TypeScript port and for helping to maintain this package.

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

Support my OSS work by following me on twitter