chainy/node_modules/deck/README.markdown

deck

Uniform and weighted shuffling and sampling for node.

examples

uniform shuffle

shuffle.js:

var deck = require('deck');
var xs = deck.shuffle([ 1, 2, 3, 4 ]);
console.log(xs);

output:

$ node shuffle.js 
[ 1, 4, 2, 3 ]

uniform sample

pick.js:

var deck = require('deck');
var x = deck.pick([ 1, 2, 3, 4 ]);
console.log(x);

output:

$ node pick.js 
2

weighted shuffle

wshuffle.js:

var deck = require('deck');
var xs = deck.shuffle({
    a : 10,
    b : 8,
    c : 2,
    d : 1,
    e : 1,
});
console.log(xs);

output:

$ node wshuffle.js 
[ 'b', 'a', 'c', 'd', 'e' ]

weighted sample

wpick.js:

var deck = require('deck');
var x = deck.pick({
    a : 10,
    b : 8,
    c : 2,
    d : 1,
    e : 1,
});
console.log(x);

output:

$ node wpick.js 
a

methods

Note: both deck(xs).pick() and deck.pick(xs) styles work.

deck.shuffle(xs)

Return a new shuffled xs without mutating the original.

If xs is an Array, return a new shuffled Array based on a unifrom distribution.

Otherwise if xs is an object, return a new shuffled Array of xs's visible keys based on the value weights of xs.

deck.pick(xs)

Sample xs without mutating xs.

If xs is an Array, return a random element from xs with a uniform distribution.

Otherwise if xs is an object, return a random key from xs biased by its normalized value.

deck.normalize(xs)

Return a new xs object where the values have been divided by the sum of all the values such that the sum of all the values in the return object is 1.

If any weights are < 0 normalize throws an error.

installation

With npm:

npm install deck