implausible
v3.1.1
Published
Generate pseudorandom numbers and sample probability distributions with optional seed and choice of algorithm.
Downloads
47
Maintainers
stassiReadme
implausible
implausible is a collection of pseudorandom number generators (PRNGs) and utilities powered by seedrandom.
Quick start
RunKit
RunKit provides one of the most direct ways to get started:
CodePen
Declare imports and global binding in the JS section to get started:
import { prng } from 'https://unpkg.com/implausible@latest?module';
window.prng = prng;Run commands in the Console section:
prng();
// example output: 0.3722007770466942Browsers
Insert the following element within the <head> tag of an HTML document:
<script src="https://unpkg.com/implausible@latest"></script>After the script is loaded, the implausible browser global is exposed:
implausible.prng();
// example output: 0.6736552471595748Node.js
With npm installed, run terminal command:
npm i implausibleOnce installed, declare method imports at the top of each JavaScript file they will be used.
ES2015
Recommended
import {
prng,
sample,
samples,
} from 'implausible';CommonJS
const {
prng,
sample,
samples,
} = require('implausible');Usage
Generate stochastic number
prng();
// example output: 0.4471833625387327
prng();
// example output: 0.18700348375416123...with a specific algorithm
Refer to the list of PRNG names for valid parameter { name } values.
prng({ name: 'xor4096' });
// example output: 0.7105067998636514Generate deterministic number
prng({ seed: 'hello.' });
// output: 0.9282578795792454
prng({ seed: 'hello.' });
// output: 0.9282578795792454...with a specific algorithm
Refer to the list of PRNG names for valid parameter { name } values.
prng({
name: 'xor4096',
seed: 'hello.',
});
// output: 0.9798525865189731Stochastic uniform sample
sample({
collection: [
'heads',
'tails',
],
});
// example output: 'tails'...with a specific algorithm
Refer to the list of PRNG names for valid parameter { name } values.
sample({
collection: [
'heads',
'tails',
],
name: 'alea',
});
// example output: 'heads'Stochastic weighted sample
sample({
collection: {
'A-': 6.3,
'A+': 35.7,
'AB-': 0.6,
'AB+': 3.4,
'B-': 1.5,
'B+': 8.5,
'O-': 6.6,
'O+': 37.4,
},
});
// example output: 'A+'...with a specific algorithm
Refer to the list of PRNG names for valid parameter { name } values.
sample({
collection: {
'A-': 6.3,
'A+': 35.7,
'AB-': 0.6,
'AB+': 3.4,
'B-': 1.5,
'B+': 8.5,
'O-': 6.6,
'O+': 37.4,
},
name: 'alea',
});
// example output: 'O+'Deterministic uniform sample
sample({
collection: [
'heads',
'tails',
],
seed: 'hello.',
});
// output: 'tails'...with a specific algorithm
Refer to the list of PRNG names for valid parameter { name } values.
sample({
collection: [
'heads',
'tails',
],
name: 'tychei',
seed: 'hello.',
});
// output: 'heads'Deterministic weighted sample
sample({
collection: {
'A-': 6.3,
'A+': 35.7,
'AB-': 0.6,
'AB+': 3.4,
'B-': 1.5,
'B+': 8.5,
'O-': 6.6,
'O+': 37.4,
},
seed: 'hello.',
});
// output: 'A-'...with a specific algorithm
Refer to the list of PRNG names for valid parameter { name } values.
sample({
collection: {
'A-': 6.3,
'A+': 35.7,
'AB-': 0.6,
'AB+': 3.4,
'B-': 1.5,
'B+': 8.5,
'O-': 6.6,
'O+': 37.4,
},
name: 'tychei',
seed: 'hello.',
});
// output: 'A+'API
List of PRNG names
The following names of pseudorandom number generators (PRNGs) are valid String inputs for the optional { name } parameter:
aleaarc4(default)tycheixor128xor4096xorshift7xorwow
All undefined seed are automatically generated by arc4 before being piped to other generators in stochastic mode.
Visit seedrandom documentation for comparative statistics on period and performance.
prng() || prng({ [name][, seed] })
Input
All parameters are optional properties of an optional Object.
| parameter | input type(s) | default | description |
| --------- | ------------- | ------- | ----------- |
| name | String | arc4 | Refer to the list of PRNG names for values. |
| seed | Number, String | undefined (stochastic) | Deterministic when provided, or stochastic when undefined. |
Output
Generates a Number within range: [0, 1) (including 0 and excluding 1).
sample({ collection[, name][, seed] })
See also: samples
Input
All parameters are properties of an Object.
| parameter | input type(s) | default | description |
| --------- | ------------- | ------- | ----------- |
| collection (required) | Array or Object of {String:Number} pairs | | Array: collection of outcomes with uniform (equally likely) probability distribution (i.e.: coin, dice). Object: histogram where the relative probability of sampling a key is determined by its Number value. |
| name | String | arc4 | Refer to the list of PRNG names for values. |
| seed | Number, String | undefined (stochastic) | Deterministic when provided, or stochastic when undefined. |
Output
Generates a String weighted random sample from a collection member or key.
samples({ collection[, count][, name][, seed] })
See also: sample
Input
All parameters are properties of an Object.
| parameter | input type(s) | default | description |
| --------- | ------------- | ------- | ----------- |
| collection (required) | Array or Object of {String:Number} pairs | | Array: collection of outcomes with uniform (equally likely) probability distribution (i.e.: coin, dice). Object: histogram where the relative probability of sampling a key is determined by its Number value. |
| count | Number | 1 | Sample size that determines output Array length. |
| name | String | arc4 | Refer to the list of PRNG names for values. |
| seed | Number, String | undefined (stochastic) | Deterministic when provided, or stochastic when undefined. |
Output
Generates an Array of weighted random sample String from a collection member or key, similar to calling sample multiple times.
Credits
Thanks to David Bau and additional authors for distributing parent package seedrandom under the MIT license.