Choice - Weighted Random Selector

Created by Hiroya Aramaki (Makihiro)

What is Weighted Random Selector ?

Weighted Random Selector is an algorithm for randomly selecting elements based on their weights.

For example.

• Drop items based on rarity.
• Events that occur with a certain probability

It can be used to determine things with probability.

Choice is a library that was created to make it easier to implement.

// This is the simplest usage.
var randomSelectedItem = items
	.ToWeightedSelector(item => item.weight)
	.SelectItemWithUnityRandom();

Great introduction article on Weighted Random Select: https://blog.bruce-hill.com/a-faster-weighted-random-choice

<a id="index" href="#index"> Table of Contents </a>

• 📥 Installation
• 🔰 Usage
  • ToWeightedSelector Overloads
    • from weighted entry pattern
    • from weighted item pattern
    • from Dictionary<Item,float> pattern
  • LINQ
  • Algorithms
    • Linear Scan
    • Binary Search
    • Alias Method
    • Speed Measurement
• 📔 Author Info
• 📜 License

<a id="installation" href="#installation"> 📥 Installation </a>

Download any version from releases.

Releases: https://github.com/mackysoft/Choice/releases

Install via git URL

Or, you can add this package by opening PackageManager and entering

https://github.com/mackysoft/Choice.git?path=Assets/MackySoft/MackySoft.Choice

from the Add package from git URL option.

Install via Open UPM

Or, you can install this package from the Open UPM registry.

More details here.

openupm add com.mackysoft.choice

<a id="usage" href="#requirements"> 🔰 Usage </a>

// To use Choice, add this namespace.
using MackySoft.Choice;

public class WeightedItem {
	public string id;
	public float weight;
}

public WeightedItem SelectItem () {
	// Prepare weighted items.
	var items = new WeightedItem[] {
		new WeightedItem { id = "🍒", weight = 8f },
		new WeightedItem { id = "🍏", weight = 4f },
		new WeightedItem { id = "🍍", weight = 0f },
		new WeightedItem { id = "🍇", weight = 6f },
		new WeightedItem { id = "🍊", weight = -1f }
	};
	
	// Create the WeightedSelector.
	var weightedSelector = items.ToWeightedSelector(item => item.weight);
	
	// The probability of each item being selected,
	// 🍒 is 44%, 🍏 is 22%, and 🍇 is 33%.
	// 🍍 and 🍊 will never be selected because their weights are less or equal to 0.
	return weightedSelector.SelectItemWithUnityRandom();
	// Same as weightedSelector.SelectItem(UnityEngine.Random.value);
}

<a id="toweightedselector-overloads" href="#toweightedselector-overloads"> ToWeightedSelector Overloads </a>

The ToWeightedSelector method has many overloads and can be used for a variety of patterns.

<a id="from-weighted-entry" href="#from-weighted-entry"> from weighted entry pattern </a>

public struct ItemEntry {
	public Item item;
	public float weight;
}

public IWeightedSelector<Item> WeightedEntryPattern () {
	var entries = new ItemEntry[] {
		new ItemEntry { item = new Item { id = "🍒" }, weight = 1f },
		new ItemEntry { item = new Item { id = "🍏" }, weight = 5f },
		new ItemEntry { item = new Item { id = "🍍" }, weight = 3f }
	};

	// Create a WeightedSelector by selecting item and weight from entry respectively.
	return entries.ToWeightedSelector(
		itemSelector: entry => entry.item,
		weightSelector: entry => entry.weight
	);
}

<a id="from-weighted-item" href="#from-weighted-item"> from weighted item pattern </a>

public class WeightedItem {
	public string id;
	public float weight;
}

public IWeightedSelector<WeightedItem> WeightedItemPattern () {
	var items = new WeightedItem[] {
		new WeightedItem { id = "🍒", weight = 1f },
		new WeightedItem { id = "🍏", weight = 5f },
		new WeightedItem { id = "🍍", weight = 3f }
	};

	// Create a WeightedSelector using the weight of the WeightedItem.
	return fromWeightedItem = items.ToWeightedSelector(weightSelector: item => item.weight);
}

<a id="from-dictionary" href="#from-dictionary"> from Dictionary<TItem,float> pattern </a>

public class Item {
	public string id;
}

public IWeightedSelector<Item> DictionaryPattern () {
	// This need a Dictionary<TItem,float>. (Strictly speaking, IEnumerable<KeyValuePair<TItem,float>>)
	var dictionary = new Dictionary<Item,float>(
		{ new Item { id = "🍒" }, 1f },
		{ new Item { id = "🍏" }, 5f },
		{ new Item { id = "🍍" }, 3f }
	);

	// Create a WeightedSelector with the dictionary key as item and value as weight.
	return dictionary.ToWeightedSelector();
}

<a id="linq" href="#linq"> LINQ </a>

Since the ToWeightedSelector method is defined as an extension of IEnumerable<T>, it can be connected from the LINQ query operators.

var randomSelectedItem = items
	.Where(item => item != null) // null check
	.ToWeightedSelector(item => item.weight)
	.SelectItemWithUnityRandom();

<a id="algorithms" href="#algorithms"> Algorithms </a>

When creating a WeightedSelector, you can specify the IWeightedSelectMethod.

var weightedSelector = items.ToWeightedSelector(
	item => item.weight,
	WeightedSelectMethod.Binary // Use the binary search algorithm.
);

All ToWeightedSelector methods can specify IWeightedSelectMethod.

If this is not specified, the linear scan algorithm will be used automatically.

<a id="linear-scan" href="#linear-scan"> Linear Scan (WeightedSelectMethod.Linear) </a>

The simplest algorithm that walks linearly along the weights. This method is an O(n) operation, where n is number of weights.

<a id="binary-search" href="#binary-search"> Binary Search (WeightedSelectMethod.Binary) </a>

The binary search algorithm that is faster than linear scan by preprocessing to store the current sum of weights.

It has an additional storage cost of O(n), but is accelerated by up to O(log(n)) for each selection, where n is number of weights.

<a id="alias-method" href="#alias-method"> Alias Method (WeightedSelectMethod.Alias) </a>

The fastest algorithm.

It takes O(n) run time to set up, but the selection is performed in O(1) run time, where n is number of weights.

Therefore, this is a very effective algorithm for selecting multiple items.

<a id="speed-measurement" href="#speed-measurement"> Speed Measurement </a>

<a id="1-items" href="#1-items"> 1 items </a>

|Iterations|1|10|100|1000|10000| |:--|:--|:--|:--|:--|:--| |Linear Scan|0.0104ms|0.0055ms|0.0081ms|0.0393ms|0.3408ms| |Binary Search|0.0091ms|0.0083ms|0.0126ms|0.0659ms|0.5944ms| |Alias Method|0.0069ms|0.0065ms|0.01ms|0.0459ms|0.4094ms|

|Iterations|1|10|100|1000|10000| |:--|:--|:--|:--|:--|:--| |Linear Scan|0.0155ms|0.0064ms|0.0077ms|0.0381ms|0.353ms| |Binary Search|0.0077ms|0.008ms|0.0123ms|0.0659ms|0.5919ms| |Alias Method|0.0062ms|0.0065ms|0.01ms|0.0462ms|0.41ms|

|Iterations|1|10|100|1000|10000| |:--|:--|:--|:--|:--|:--| |Linear Scan|0.009ms|0.0053ms|0.0081ms|0.0378ms|0.3388ms| |Binary Search|0.0073ms|0.0079ms|0.0129ms|0.0653ms|0.5927ms| |Alias Method|0.0054ms|0.0062ms|0.0104ms|0.0461ms|0.4194ms|

<a id="10-items" href="#10-items"> 10 items </a>

|Iterations|1|10|100|1000|10000| |:--|:--|:--|:--|:--|:--| |Linear Scan|0.0113ms|0.0077ms|0.0182ms|0.1219ms|1.19ms| |Binary Search|0.0109ms|0.0114ms|0.0237ms|0.158ms|1.4975ms| |Alias Method|0.0136|0.022ms|0.0151ms|0.0601ms|0.5041ms|

|Iterations|1|10|100|1000|10000| |:--|:--|:--|:--|:--|:--| |Linear Scan|0.012ms|0.0072ms|0.0174ms|0.1272ms|1.1738ms| |Binary Search|0.0095ms|0.0099ms|0.023ms|0.16ms|1.5503ms| |Alias Method|0.0141ms|0.0104ms|0.0148ms|0.0618ms|0.5235ms|

|Iterations|1|10|100|1000|10000| |:--|:--|:--|:--|:--|:--| |Linear Scan|0.0095ms|0.009ms|0.0179ms|0.1216ms|1.1503ms| |Binary Search|0.0096ms|0.0103ms|0.0225ms|0.1572ms|1.4991ms| |Alias Method|0.0129ms|0.0105ms|0.015ms|0.0607ms|0.5176ms|

<a id="100-items" href="#100-items"> 100 items </a>

|Iterations|1|10|100|1000|10000| |:--|:--|:--|:--|:--|:--| |Linear Scan|0.0201ms|0.024ms|0.0822ms|0.741ms|7.2211ms| |Binary Search|0.0212ms|0.0211ms|0.0433ms|0.3118ms|2.6434ms| |Alias Method|0.0717ms|0.0364ms|0.0395ms|0.086ms|0.5462ms|

|Iterations|1|10|100|1000|10000| |:--|:--|:--|:--|:--|:--| |Linear Scan|0.0231ms|0.0247ms|0.0855ms|0.7027ms|7.0025ms| |Binary Search|0.0224ms|0.0231ms|0.0441ms|0.2776ms|2.6521ms| |Alias Method|*0.039ms|0.0358ms