Stochasm
A JavaScript component to create functions that generate random values.
Why?
It can be very useful to generate random numbers that are governed by properties of different types of distributions. Such distributions are useful for modeling numerical behavior and response of systems.
Fork
This module was forked from https://github.com/heydenberk/stochasm that was created by Eric Heydenberk. Why did I fork it?
- Unmaintained
- Written in CoffeeScript
- Not a UMD
- No tests
- No support to modify the random number generation
Rather than pester Eric about changing any of the above, a fork seemed more reasonable.
Name
stochasm
is a portmanteau of stochastic and chasm.
Install
Node.js/Browserify
npm install --save stochasm
Component
component install jprichardson/stochasm
Bower
bower install stochasm
Script
Usage
To create a stochasm
object, simply invoke the function and pass it an options
object with a kind
property. If not provided, kind is 'float'.
Valid kinds include float
, integer
, set
.
Floating-point Decimals
It's very easy generate a float between 0 and 1.
var stochasm = var generator = generatornext; // 0.9854211050551385generatornext; // 0.8784450970124453generatornext; // 0.1592887439765036
This is not very exciting because it simply wraps the built-in Math.random
method.
Floats from an Interval
Specifying a min and a max allows us to create random numbers in the interval (min, max), not inclusive.
var radianGenerator = radianGeneratornext; // 3.7084574239999655radianGeneratornext; // 1.021138034566463radianGeneratornext; // 4.012664264853087
Floats from a Normal Distribution
We can also generate random floats from a normal distribution. Min and max are optional, and when provided will result in truncation of all results outside of [min, max].
var testScores = testScoresnext; // 59.437160028200125testScoresnext; // 80.18612670399554testScoresnext; // 75.81242027226946
Integers
For integers, the interval [min, max] is inclusive.
var die = dienext; // 6dienext; // 1dienext; // 2
if next()
feels out of place for your use case, just rename the method:
dieroll = dienextdie //4
Multiple Results
If the next
method (or a method aliased to it) is passed an integer n
, it will return an n-length array of results. Using the die instance from the previous example:
die; // [5]die; // [5, 3]die; // [6, 3, 6, 6, 5]
From Sets
We can generate random values from arbitary sets.
var dayGenerator = kind: "set" values: "monday" "tuesday" "wednesday" "thursday" "friday" "saturday" "sunday";dayGeneratornext; // fridaydayGeneratornext; // monday dayGeneratornext; // monday
From Sets with Weights
What if we favor the weekend? Well, we can pass weights
, an array of the same length as values
consisting of probabilities out of 1 that correspond to values
.
var biasedDayGenerator = kind: "set" values: "monday" "tuesday" "wednesday" "thursday" "friday" "saturday" "sunday" weights: 01 01 01 01 01 025 025;biasedDayGeneratornext; // thursdaybiasedDayGeneratornext; // sunday biasedDayGeneratornext; // saturday
From Sets Without Replacement
Note: This functionality may be removed.
Passing a replacement
property with a falsy value will result in each random
value generation to be removed from the set.
var chores = kind: "set" values: "floors" "windows" "dishes" replacement: false;var myChore = choresnext; // "windows"var yourChore = choresnext; // "floors"var hisChore = choresnext; // "dishes"var noOnesChore = choresnext; // undefined
Mutators
The constructor accepts an optional final argument which is passed the output of the random value generator. Its return value becomes the return value of next or its alias. To generate random boolean values, we can do:
var booleanGenerator = kind: "integer" min: 0 max: 1 Boolean; booleanGeneratornext; // falsebooleanGeneratornext; // truebooleanGeneratornext; // true
We can map the previously mentioned radianGenerator
to the cosine of its values.
var radianSineGenerator = min: 0 max: MathPI * 2 Mathcos;radianSineGeneratornext; // -0.31173382958096524radianSineGeneratornext; // -0.6424354006937544radianSineGeneratornext; // 0.6475980728835664
Mutators remember their previous result and, at each generation, apply the results of a specified stochasm to create a new result.
(This is functionally equivalent to a Markov chain.)
var drunkardsWalk = kind: "integer" min: -1 max: 1 { return a + b; }; drunkardsWalkvalue = 0; // Sets the initial valuedrunkardsWalknext10; // [-1, -2, -2, -1, -1, -1, 0, 1, 1, 2]drunkardsWalknext10; // [3, 3, 3, 2, 1, 0, -1, 0, 0, 0]drunkardsWalknext10; // [0, 1, 0, -1, 0, 0, 1, 2, 1, 1]
Let's model a bank account's balance. How much money might you have after 10 years if you start with $1000, add $1000 every year, and get interest at a random rate between 1% and 5%?
var { return principal + 1000 * interestRate;};var savingsAccountBalance = kind: "float" min: 101 max: 105 addInterest; savingsAccountBalancevalue = 1000; // Sets the initital valuesavingsAccountBalancenext10;/*[ 2096.2402432970703, 3177.3792999428224, 4339.349049328612, 5441.863800747634, 6507.916293297546, 7669.519280743041, 9011.783840249629, 10225.82489660009, 11630.122217972781, 12782.667463879243]*/
Multiple Generators
If the stochasm function is passed multiple configuration objects, next
(or its alias) returns an array of each random generated value.
To generate a random point, we might do:
var x = kind: 'integer' min: 0 max: 480 ;var y = kind: 'integer' min: 0 max: 360 ;var { return x: values0 y: values1 ;};var randomPoint = x y mutator; randomPointnext; // { x: 79, y: 65 }randomPointnext; // { x: 151, y: 283 }randomPointnext; // { x: 5, y: 253 }
Your Own Random Number Generator
Want to bring your own random number generator to the party? Whether you're working with Node.js and want to use crypto.getRandomValues()
or in the browser and want to use window.crypto.getRandomValues()
, you can. You could also return a constant to see how your system may respond to certain conditions in testing.
Note: At this time, it's assumed that any function that you set rand
to will return a number in the range of [0,1)
.
var stochasm = var radianGenerator = radianGenerator { return 04 }
Credits
As stated above, this code was forked from the Node.js module stochator
(https://github.com/heydenberk/stochasm) that was created by Eric Heydenberk. Eric Heydenberk deserves much of the credit for coming up with such an awesome idea.
License
It made sense to just keep the license the same. MPLv2.
(MPLv2 License)
Copyright 2013, Eric Heydenberk and JP Richardson