Categorical distribution implemented in JavaScript.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
test
.gitignore
README.md
categorical.js
package.json
yarn.lock

README.md

categorical

categorical is an impementation of a categorical distribution in JavaScript. Why do you care about it?

It allows you to do fancy things like randomly draw from several different outcomes that all have different probabilities. Imagine you have a bunch of different fruits, and you want to randomly pick one to eat. However, you like some fruits more than others.

var fruits = [
  { name: "apple", like: 10 },
  { name: "banana", like: 15 },
  { name: "peach", like: 20 }
];

Fruits that you like more should show up more when you randomly draw, but you still sometimes want to pick fruits that you like less. Categorical to the rescue!

var categorical = require("categorical"),
  distribution,
  fruitResults = [0, 0, 0],
  fruit,
  i;

function calculateScoreForFruit(fruit) {
  return fruit.like;
}

distribution = categorical.createDistribution(fruits, calculateScoreForFruit);

// test the results
for (i = 0; i < 10000; i++) {
  fruit = categorical.draw(distribution);
  if (fruit.name === "apple") {
    fruit[0]++;
  } else if (fruit.name === "banana") {
    fruit[1]++;
  } else {
    fruit[2]++;
  }
}

console.log(
  "apple: " + fruit[0] + ", banana: " + fruit[1] + ", peach: " + fruit[2]
);

Installation

npm install categorical

API

categorical is pretty simple. It only has two calls:

categorical.createDistribution(items, scoreFunction)

Creates and returns a categorical distribution.

items - An array of items to use to create the distribution.

scoreFunction - function(item) that returns a numeric score for an individual item from items.

Returns the distribution. An array of objects containing the probability windows for each item, along with the item itself.

var fruits = [
  { name: "apple", like: 10 },
  { name: "banana", like: 15 },
  { name: "peach", like: 20 }
];

function calculateScoreForFruit(fruit) {
  return fruit.like;
}

distribution = categorical.createDistribution(fruits, calculateScoreForFruit);

categorical.draw(distribution)

Draw a random item from the distribution.

distribution is the distribution returned from a call to createDistribution.

Returns the random item returned from the distribution.

var fruit = categorical.draw(distribution);
console.log(fruit); // will be either 'apple', 'banana', or 'peach'