Added basic np.random.choice functionality (Fixed #310)

* Stub files for np.random.choice

* Simplest random.choice functionality

* Simple random.choice with weighted probabilities

* Unit test stubs and updated documentation (np.random.choice)

* Added Ignore markers to tests for unimplemented features

* random.choice handles shape=null

* Improved unit tests for np.random.choice

* Added documentation to np.searchsorted

Author: Plankton555

src/NumSharp.Core/Random/np.random.choice.cs

@@ -0,0 +1,56 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Text;
+
+namespace NumSharp
+{
+    public partial class NumPyRandom
+    {
+        /// <summary>
+        /// Generates a random sample from a given 1-D array
+        /// </summary>
+        /// <param name="arr">If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a were np.arange(a)</param>
+        /// <param name="shape">Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.</param>
+        /// <param name="replace">Whether the sample is with or without replacement</param>
+        /// <param name="probabilities">The probabilities associated with each entry in a. If not given the sample assumes a uniform distribution over all entries in a.</param>
+        /// <remarks>https://docs.scipy.org/doc/numpy/reference/generated/numpy.random.choice.html</remarks>
+        public NDArray choice(NDArray arr, Shape shape = null, bool replace = true, double[] probabilities = null)
+        {
+            int arrSize = arr.len;
+            NDArray idx = np.random.choice(arrSize, shape, probabilities: probabilities);
+            return arr[idx];
+        }
+
+        /// <summary>
+        ///  Generates a random sample from a given 1-D array
+        /// </summary>
+        /// <param name="a">If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a were np.arange(a)</param>
+        /// <param name="shape">Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. Default is None, in which case a single value is returned.</param>
+        /// <param name="replace">Whether the sample is with or without replacement</param>
+        /// <param name="probabilities">The probabilities associated with each entry in a. If not given the sample assumes a uniform distribution over all entries in a.</param>
+        /// <remarks>https://docs.scipy.org/doc/numpy/reference/generated/numpy.random.choice.html</remarks>
+        public NDArray choice(int a, Shape shape = null, bool replace = true, double[] probabilities = null)
+        {
+            if (shape is null)
+            {
+                shape = 1;
+            }
+            NDArray arr = np.arange(a);
+            NDArray idx = null;
+            //Debug.WriteLine($"arr: {arr}");
+            if (probabilities is null)
+            {
+                idx = np.random.randint(0, arr.len, shape);
+            }
+            else
+            {
+                NDArray cdf = np.cumsum(probabilities);
+                cdf /= cdf[cdf.len - 1];
+                NDArray uniformSamples = np.random.uniform(0, 1, shape);
+                idx = np.searchsorted(cdf, uniformSamples);
+            }
+            return idx;
+        }
+    }
+}

src/NumSharp.Core/Sorting_Searching_Counting/np.searchsorted.cs

@@ -0,0 +1,61 @@
+using System;
+using System.Collections.Generic;
+using System.Text;
+
+namespace NumSharp
+{
+    public static partial class np
+    {
+        /// <summary>
+        /// Find indices where elements should be inserted to maintain order.
+        ///
+        /// Find the indices into a sorted array a such that, if the corresponding elements in v were inserted before the indices, the order of a would be preserved.
+        /// </summary>
+        /// <param name="a">Input array. Must be sorted in ascending order.</param>
+        /// <param name="v">Values to insert into a.</param>
+        /// <returns>Array of insertion points with the same shape as v.</returns>
+        /// <remarks>https://docs.scipy.org/doc/numpy/reference/generated/numpy.searchsorted.html</remarks>
+        public static NDArray searchsorted(NDArray a, NDArray v)
+        {
+            // TODO currently no support for multidimensional a
+            NDArray output = new int[v.shape[0]];
+            for (int i = 0; i < v.size; i++)
+            {
+                double target = v[i];
+                int idx = binarySearchRightmost(a, target);
+                output[i] = idx;
+            }
+            return output;
+        }
+
+        /// <summary>
+        /// Find the (right-most) position of a target value within a sorted array.
+        /// </summary>
+        /// <param name="arr">Sorted array.</param>
+        /// <param name="target">Target value to find position of.</param>
+        /// <returns>Would-be index of target value within the array.</returns>
+        /// <remarks>https://en.wikipedia.org/wiki/Binary_search_algorithm</remarks>
+        private static int binarySearchRightmost(NDArray arr, double target)
+        {
+            // TODO should probably not work on NDArray? Does it make sense to do binary search on multidimensional arrays?
+            int L = 0;
+            int R = arr.size;
+            int m;
+            double val;
+            while (L < R)
+            {
+                m = (L + R) / 2;
+                val = arr[m];
+                if (val < target)
+                {
+                    L = m + 1;
+                }
+                else
+                {
+                    R = m;
+                }
+            }
+            return L;
+        }
+    }
+}

test/NumSharp.UnitTest/Random/np.random.choice.Test.cs

@@ -0,0 +1,132 @@
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Text;
+
+namespace NumSharp.UnitTest.RandomSampling
+{
+    [TestClass]
+    public class NpRandomChoiceTests : TestClass
+    {
+        [TestMethod]
+        public void UniformOneSample()
+        {
+            // Generate a uniform random sample from np.arange(5) of size 1:
+            // This is equivalent to np.random.randint(0,5,1)
+            int low = 0;
+            int high = 5;
+            int nrSamples = 1;
+
+            NDArray actual = np.random.choice(high); // Not specifying size means 1 single value is wanted
+
+            Assert.AreEqual(actual.len, nrSamples, "Unexpected number of elements");
+
+            // Verify that all elements in output are within the range
+            for (int i = 0; i < actual.len; i++)
+            {
+                Assert.IsTrue(actual[i] >= low, "Element was less than expected");
+                Assert.IsTrue(actual[i] < high, "Element was greater than expected");
+            }
+        }
+        [TestMethod]
+        public void UniformMultipleSample()
+        {
+            // Generate a uniform random sample from np.arange(5) of size 3:
+            // This is equivalent to np.random.randint(0,5,3)
+            int low = 0;
+            int high = 5;
+            int nrSamples = 3;
+
+            NDArray actual = np.random.choice(high, nrSamples);
+
+            Assert.AreEqual(actual.len, nrSamples, "Unexpected number of elements");
+
+            // Verify that all elements in output are within the range
+            for (int i = 0; i < actual.len; i++)
+            {
+                Assert.IsTrue(actual[i] >= low, "Element was less than expected");
+                Assert.IsTrue(actual[i] < high, "Element was greater than expected");
+            }
+        }
+
+        [TestMethod]
+        public void NonUniformSample()
+        {
+            // Generate a non-uniform random sample from np.arange(5) of size 3:
+            int low = 0;
+            int high = 5;
+            int nrSamples = 3;
+            double[] probabilities = new double[] {0.1, 0, 0.3, 0.6, 0};
+
+            NDArray actual = np.random.choice(5, nrSamples, probabilities: probabilities);
+
+            Assert.AreEqual(actual.len, nrSamples, "Unexpected number of elements");
+
+            // Verify that all elements in output are within the range
+            for (int i = 0; i < actual.len; i++)
+            {
+                Assert.IsTrue(actual[i] >= low, "Element was less than expected");
+                Assert.IsTrue(actual[i] < high, "Element was greater than expected");
+                Assert.IsTrue(actual[i] != 1, "Sampled zero-probability element");
+                Assert.IsTrue(actual[i] != 4, "Sampled zero-probability element");
+            }
+        }
+
+        [TestMethod]
+        [Ignore("Choice without replacement not implemented yet")]
+        public void UniformSampleWithoutReplace()
+        {
+            NDArray actual = np.random.choice(5, 3, replace: false);
+            Assert.Fail("Not implemented");
+        }
+
+        [TestMethod]
+        [Ignore("Choice without replacement not implemented yet")]
+        public void NonUniformSampleWithoutReplace()
+        {
+            double[] probabilities = new double[] { 0.1, 0, 0.3, 0.6, 0 };
+            NDArray actual = np.random.choice(5, 3, replace: false, probabilities: probabilities);
+            Assert.Fail("Not implemented");
+        }
+
+        [TestMethod]
+        [Ignore("Choice with string arrays not implemented yet")]
+        public void StringArraySample1()
+        {
+            int nrSamples = 5;
+
+            NDArray aa_milne_arr = new string[] { "pooh", "rabbit", "piglet", "Christopher" };
+            double[] probabilities = new double[] { 0.5, 0.1, 0.0, 0.3 };
+
+            NDArray actual = np.random.choice(aa_milne_arr, nrSamples, probabilities: probabilities);
+
+            Assert.AreEqual(actual.len, nrSamples, "Unexpected number of elements");
+
+            // Verify that all elements in output are within the possibilities
+            for (int i = 0; i < actual.len; i++)
+            {
+                Assert.IsTrue((string)actual[i] != (string)aa_milne_arr[2], "Sampled zero-probability element");
+            }
+        }
+
+        [TestMethod]
+        public void IntegerArraySample()
+        {
+            int nrSamples = 5;
+
+            NDArray int_arr = new int[] { 42, 96, 3, 101 };
+            double[] probabilities = new double[] { 0.5, 0.1, 0.0, 0.3 };
+
+            NDArray actual = np.random.choice(int_arr, nrSamples, probabilities: probabilities);
+
+            Assert.AreEqual(actual.len, nrSamples, "Unexpected number of elements");
+
+            // Verify that all elements in output are within the possibilities
+            for (int i = 0; i < actual.len; i++)
+            {
+                Assert.IsTrue((int)actual[i] != (int)int_arr[2], "Sampled zero-probability element");
+            }
+        }
+    }
+}