Seedable random number generator supporting many common distributions.
Welcome to the most random module on npm! 😜
- Simple API (make easy things easy and hard things possible)
- TypeScript supported!
- 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
npm install --save random
# or
yarn add random
const random = require('random')
// or
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:
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()
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, defaultMath.random
)
Type: function ()
- See: RNG.clone
Creates a new Random
instance, optionally specifying parameters to
set a new seed.
Type: function (args, seed, opts): Random
args
...anyseed
string? Optional seed for new RNG.opts
object? Optional config for new RNG options.
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)
Patches Math.random
with this Random instance's PRNG.
Type: function ()
Restores a previously patched Math.random
to its original value.
Type: function ()
Convenience wrapper around this.rng.next()
Returns a floating point number in [0, 1).
Type: function (): number
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, default0
)max
number Upper bound (float, exclusive) (optional, default1
)
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, default0
)max
number Upper bound (integer, inclusive) (optional, default1
)
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, default0
)max
number Upper bound (integer, inclusive) (optional, default1
)
Samples a uniform random boolean value.
Convence wrapper around random.uniformBoolean()
Type: function (): boolean
Samples a uniform random boolean value.
Convence wrapper around random.uniformBoolean()
Type: function (): boolean
Generates a Continuous uniform distribution.
Type: function (min, max): function
min
number Lower bound (float, inclusive) (optional, default0
)max
number Upper bound (float, exclusive) (optional, default1
)
Generates a Discrete uniform distribution.
Type: function (min, max): function
min
number Lower bound (integer, inclusive) (optional, default0
)max
number Upper bound (integer, inclusive) (optional, default1
)
Generates a Discrete uniform distribution,
with two possible outcomes, true
or `false.
This method is analogous to flipping a coin.
Type: function (): function
Generates a Normal distribution.
Type: function (mu, sigma): function
Generates a Log-normal distribution.
Type: function (mu, sigma): function
mu
number Mean of underlying normal distribution (optional, default0
)sigma
number Standard deviation of underlying normal distribution (optional, default1
)
Generates a Bernoulli distribution.
Type: function (p): function
p
number Success probability of each trial. (optional, default0.5
)
Generates a Binomial distribution.
Type: function (n, p): function
n
number Number of trials. (optional, default1
)p
number Success probability of each trial. (optional, default0.5
)
Generates a Geometric distribution.
Type: function (p): function
p
number Success probability of each trial. (optional, default0.5
)
Generates a Poisson distribution.
Type: function (lambda): function
lambda
number Mean (lambda > 0) (optional, default1
)
Generates an Exponential distribution.
Type: function (lambda): function
lambda
number Inverse mean (lambda > 0) (optional, default1
)
Generates an Irwin Hall distribution.
Type: function (n): function
n
number Number of uniform samples to sum (n >= 0) (optional, default1
)
Generates a Bates distribution.
Type: function (n): function
n
number Number of uniform samples to average (n >= 1) (optional, default1
)
Generates a Pareto distribution.
Type: function (alpha): function
alpha
number Alpha (optional, default1
)
-
Distributions
- uniform
- uniformInt
- uniformBoolean
- normal
- logNormal
- chiSquared
- cauchy
- fischerF
- studentT
- bernoulli
- binomial
- negativeBinomial
- geometric
- poisson
- exponential
- gamma
- hyperExponential
- weibull
- beta
- laplace
- irwinHall
- bates
- pareto
-
Generators
- pluggable prng
- port more prng from boost
- custom entropy
-
Misc
- browser support via rollup
- basic docs
- basic tests
- test suite
- initial release!
- typescript support
- 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.
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.
MIT © Travis Fischer
Support my OSS work by following me on twitter