Add the "Weighted Random" algorithm (trekhleb#792)

* Add the link to the Weighted Random algorithm to the main README.

* Add Weighted Random implementation and tests.

* Add Weighted Random README.

* Add Weighted Random README.

* Add Weighted Random README.

README.md

@@ -156,6 +156,8 @@ a set of rules that precisely define a sequence of operations.
   * `B` [k-Means](src/algorithms/ml/k-means) - k-Means clustering algorithm
 * **Image Processing**
   * `B` [Seam Carving](src/algorithms/image-processing/seam-carving) - content-aware image resizing algorithm
+* **Statistics**
+  * `B` [Weighted Random](src/algorithms/statistics/weighted-random) - select the random item from the list based on items' weights
 * **Uncategorized**
   * `B` [Tower of Hanoi](src/algorithms/uncategorized/hanoi-tower)
   * `B` [Square Matrix Rotation](src/algorithms/uncategorized/square-matrix-rotation) - in-place algorithm

src/algorithms/statistics/weighted-random/README.md

@@ -0,0 +1,141 @@
+# Weighted Random
+
+## What is "Weighted Random"
+
+Let's say you have a list of **items**. Item could be anything. For example, we may have a list of fruits and vegetables that you like to eat: `[ '🍌', '🍎', '🥕' ]`.
+
+The list of **weights** represent the weight (or probability, or importance) of each item. Weights are numbers. For example, the weights like `[3, 7, 1]` would say that:
+
+- you would like to eat `🍎 apples` more often (`7` out of `3 + 7 + 1 = 11` times),
+- then you would like to eat `bananas 🍌` less often (only `3` out of `11` times),
+- and the `carrots 🥕` you really don't like (want to eat it only `1` out of `11` times).
+
+> If we speak in terms of probabilities than the weights list might be an array of floats that sum up to `1` (i.e. `[0.1, 0.5, 0.2, 0.2]`).
+
+The **Weighted Random** in this case will be the function that will randomly return you the item from the list, and it will take each item's weight into account, so that items with the higher weight will be picked more often.
+
+Example of the function interface:
+
+```javascript
+const items =   [ '🍌', '🍎', '🥕' ];
+const weights = [  3,    7,    1  ];
+
+function weightedRandom(items, weights) {
+  // implementation goes here ...
+}
+
+const nextSnackToEat = weightedRandom(items, weights); // Could be '🍎'
+```
+
+## Applications of Weighted Random
+
+- In [Genetic Algorithm](https://en.wikipedia.org/wiki/Genetic_algorithm) the weighted random is used during the "Selection" phase, when we need to select the fittest/strongest individuums based on their fitness score for mating and for producing the next stronger generation. You may find an **example** in the [Self-Parking Car in 500 Lines of Code](https://trekhleb.dev/blog/2021/self-parking-car-evolution/) article.
+- In [Recurrent Neural Networks (RNN)](https://en.wikipedia.org/wiki/Recurrent_neural_network) when trying to decide what letter to choose next (to form the sentence) based on the next letter probability. You may find an **example** in the [Recipe Generation using Recurrent Neural Network (RNN)](https://nbviewer.org/github/trekhleb/machine-learning-experiments/blob/master/experiments/recipe_generation_rnn/recipe_generation_rnn.ipynb) Jupyter notebook.
+- In [Nginx Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/) to send HTTP requests more often to the servers with the higher weights.
+- And more...
+
+## The Algorithm
+
+The **straightforward approach** would be to:
+
+1. Repeat each item in the list according to its weight.
+2. Pick the random item from the list.
+
+For example in our case with fruits and vegetables we could generate the following list of size `3 + 7 + 1 = 11`:
+
+```javascript
+const items =   [ '🍌', '🍎', '🥕' ];
+const weights = [  3,    7,    1  ];
+
+// Repeating the items based on weights.
+const weightedItems = [
+  '🍌', '🍌', '🍌',
+  '🍎', '🍎', '🍎', '🍎', '🍎', '🍎', '🍎',
+  '🥕',
+];
+
+// And now just pick the random item from weightedItems array.
+```
+
+However, as you may see, this approach may require a lot of memory, in case if the objects are heavy, and in case if we have a lot of them to repeat in `weightedItems` list.
+
+The **more efficient approach** would be to:
+
+1. Prepare the list of cumulative weights for each item (i.e. the `cumulativeWeights` list which will have the same number of elements as the original `weights` list). In our case it will look like this: `cumulativeWeights = [3, 3 + 7, 3 + 7 + 1] = [3, 10, 11]`
+2. Generate the random number `randomNumber` from `0` to the highest cumulative weight value. In our case the random number will be in a range of `[0..11]`. Let's say that we have `randomNumber = 8`.
+3. Go through the `cumulativeWeights` list from left to right and pick the first element which is higher or equal to the `randomNumber`. The index of such element we will use to pick the item from the `items` array.
+
+The idea behind this approach is that the higher weights will "occupy" more numeric space. Therefore, there is a higher chance that the random number will fall into the "higher weight numeric bucket".
+
+```javascript
+const weights =           [3, 7,  1 ];
+const cumulativeWeights = [3, 10, 11];
+
+// In a pseudo-representation we may think about the cumulativeWeights array like this.
+const pseudoCumulativeWeights = [
+  1, 2, 3,               // <-- [3] numbers
+  4, 5, 6, 7, 8, 9, 10,  // <-- [7] numbers
+  11,                    // <-- [1] number
+];
+```
+
+Here is an example of how the `weightedRandom` function might be implemented:
+
+```javascript
+/**
+ * Picks the random item based on its weight.
+ * The items with higher weight will be picked more often (with a higher probability).
+ *
+ * For example:
+ * - items = ['banana', 'orange', 'apple']
+ * - weights = [0, 0.2, 0.8]
+ * - weightedRandom(items, weights) in 80% of cases will return 'apple', in 20% of cases will return
+ * 'orange' and it will never return 'banana' (because probability of picking the banana is 0%)
+ *
+ * @param {any[]} items
+ * @param {number[]} weights
+ * @returns {{item: any, index: number}}
+ */
+export default function weightedRandom(items, weights) {
+  if (items.length !== weights.length) {
+    throw new Error('Items and weights must be of the same size');
+  }
+
+  if (!items.length) {
+    throw new Error('Items must not be empty');
+  }
+
+  // Preparing the cumulative weights array.
+  // For example:
+  // - weights = [1, 4, 3]
+  // - cumulativeWeights = [1, 5, 8]
+  const cumulativeWeights = [];
+  for (let i = 0; i < weights.length; i += 1) {
+    cumulativeWeights[i] = weights[i] + (cumulativeWeights[i - 1] || 0);
+  }
+
+  // Getting the random number in a range of [0...sum(weights)]
+  // For example:
+  // - weights = [1, 4, 3]
+  // - maxCumulativeWeight = 8
+  // - range for the random number is [0...8]
+  const maxCumulativeWeight = cumulativeWeights[cumulativeWeights.length - 1];
+  const randomNumber = maxCumulativeWeight * Math.random();
+
+  // Picking the random item based on its weight.
+  // The items with higher weight will be picked more often.
+  for (let itemIndex = 0; itemIndex < items.length; itemIndex += 1) {
+    if (cumulativeWeights[itemIndex] >= randomNumber) {
+      return {
+        item: items[itemIndex],
+        index: itemIndex,
+      };
+    }
+  }
+}
+```
+
+## Implementation
+
+- Check the [weightedRandom.js](weightedRandom.js) file for the implementation of the `weightedRandom()` function.
+- Check the [weightedRandom.test.js](__test__/weightedRandom.test.js) file for the tests-cases.

src/algorithms/statistics/weighted-random/__test__/weightedRandom.test.js

@@ -0,0 +1,64 @@
+import weightedRandom from '../weightedRandom';
+
+describe('weightedRandom', () => {
+  it('should throw an error when the number of weights does not match the number of items', () => {
+    const getWeightedRandomWithInvalidInputs = () => {
+      weightedRandom(['a', 'b', 'c'], [10, 0]);
+    };
+    expect(getWeightedRandomWithInvalidInputs).toThrow('Items and weights must be of the same size');
+  });
+
+  it('should throw an error when the number of weights or items are empty', () => {
+    const getWeightedRandomWithInvalidInputs = () => {
+      weightedRandom([], []);
+    };
+    expect(getWeightedRandomWithInvalidInputs).toThrow('Items must not be empty');
+  });
+
+  it('should correctly do random selection based on wights in straightforward cases', () => {
+    expect(weightedRandom(['a', 'b', 'c'], [1, 0, 0])).toEqual({ index: 0, item: 'a' });
+    expect(weightedRandom(['a', 'b', 'c'], [0, 1, 0])).toEqual({ index: 1, item: 'b' });
+    expect(weightedRandom(['a', 'b', 'c'], [0, 0, 1])).toEqual({ index: 2, item: 'c' });
+    expect(weightedRandom(['a', 'b', 'c'], [0, 1, 1])).not.toEqual({ index: 0, item: 'a' });
+    expect(weightedRandom(['a', 'b', 'c'], [1, 0, 1])).not.toEqual({ index: 1, item: 'b' });
+    expect(weightedRandom(['a', 'b', 'c'], [1, 1, 0])).not.toEqual({ index: 2, item: 'c' });
+  });
+
+  it('should correctly do random selection based on wights', () => {
+    // Number of times we're going to select the random items based on their weights.
+    const ATTEMPTS_NUM = 1000;
+    // The +/- delta in the number of times each item has been actually selected.
+    // I.e. if we want the item 'a' to be selected 300 times out of 1000 cases (30%)
+    // then 267 times is acceptable since it is bigger that 250 (which is 300 - 50)
+    // ans smaller than 350 (which is 300 + 50)
+    const THRESHOLD = 50;
+
+    const items = ['a', 'b', 'c']; // The actual items values don't matter.
+    const weights = [0.1, 0.3, 0.6];
+
+    const counter = [];
+    for (let i = 0; i < ATTEMPTS_NUM; i += 1) {
+      const randomItem = weightedRandom(items, weights);
+      if (!counter[randomItem.index]) {
+        counter[randomItem.index] = 1;
+      } else {
+        counter[randomItem.index] += 1;
+      }
+    }
+
+    for (let itemIndex = 0; itemIndex < items.length; itemIndex += 1) {
+      /*
+        i.e. item with the index of 0 must be selected 100 times (ideally)
+        or with the threshold of [100 - 50, 100 + 50] times.
+
+        i.e. item with the index of 1 must be selected 300 times (ideally)
+        or with the threshold of [300 - 50, 300 + 50] times.
+
+        i.e. item with the index of 2 must be selected 600 times (ideally)
+        or with the threshold of [600 - 50, 600 + 50] times.
+       */
+      expect(counter[itemIndex]).toBeGreaterThan(ATTEMPTS_NUM * weights[itemIndex] - THRESHOLD);
+      expect(counter[itemIndex]).toBeLessThan(ATTEMPTS_NUM * weights[itemIndex] + THRESHOLD);
+    }
+  });
+});

src/algorithms/statistics/weighted-random/weightedRandom.js

@@ -0,0 +1,52 @@
+/**
+ * Picks the random item based on its weight.
+ * The items with higher weight will be picked more often (with a higher probability).
+ *
+ * For example:
+ * - items = ['banana', 'orange', 'apple']
+ * - weights = [0, 0.2, 0.8]
+ * - weightedRandom(items, weights) in 80% of cases will return 'apple', in 20% of cases will return
+ * 'orange' and it will never return 'banana' (because probability of picking the banana is 0%)
+ *
+ * @param {any[]} items
+ * @param {number[]} weights
+ * @returns {{item: any, index: number}}
+ */
+/* eslint-disable consistent-return */
+export default function weightedRandom(items, weights) {
+  if (items.length !== weights.length) {
+    throw new Error('Items and weights must be of the same size');
+  }
+
+  if (!items.length) {
+    throw new Error('Items must not be empty');
+  }
+
+  // Preparing the cumulative weights array.
+  // For example:
+  // - weights = [1, 4, 3]
+  // - cumulativeWeights = [1, 5, 8]
+  const cumulativeWeights = [];
+  for (let i = 0; i < weights.length; i += 1) {
+    cumulativeWeights[i] = weights[i] + (cumulativeWeights[i - 1] || 0);
+  }
+
+  // Getting the random number in a range of [0...sum(weights)]
+  // For example:
+  // - weights = [1, 4, 3]
+  // - maxCumulativeWeight = 8
+  // - range for the random number is [0...8]
+  const maxCumulativeWeight = cumulativeWeights[cumulativeWeights.length - 1];
+  const randomNumber = maxCumulativeWeight * Math.random();
+
+  // Picking the random item based on its weight.
+  // The items with higher weight will be picked more often.
+  for (let itemIndex = 0; itemIndex < items.length; itemIndex += 1) {
+    if (cumulativeWeights[itemIndex] >= randomNumber) {
+      return {
+        item: items[itemIndex],
+        index: itemIndex,
+      };
+    }
+  }
+}