@punkeel/random

2.1.3 • Public • Published

random

Seedable random number generator supporting many common distributions.

NPM Build Status JavaScript Style Guide

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

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

Package Sidebar

Install

npm i @punkeel/random

Weekly Downloads

0

Version

2.1.3

License

MIT

Unpacked Size

88.4 kB

Total Files

41

Last publish

Collaborators

  • punkeel