Methods for sampling by specifying probability of element inclusion

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Added the SequenceSampler interface's methods to SequenceReservoirSampler.
 * Added the SequenceSampler interface's methods to SequencePoolSampler.
 * Added the SequenceSampler interface's methods to SequenceInsertionSampler.
+* Methods to sample by specifying probability of including element in sample to the classes that implement SequenceSampler
+  including SequenceReservoirSampler, SequencePoolSampler, SequenceInsertionSampler, and SequenceCompositeSampler.
 
 ### Changed
 * SequenceSampler converted from a utility class of static methods to an interface, retaining the existing static

src/main/java/org/cicirello/sequences/SequenceCompositeSampler.java

@@ -22,6 +22,7 @@
 package org.cicirello.sequences;
 
 import java.util.random.RandomGenerator;
+import org.cicirello.math.rand.RandomVariates;
 
 /**
  * SequenceCompositeSampler generates random samples of array elements, without replacement.
@@ -153,6 +154,133 @@ public <T> T[] nextSample(T[] source, int k, T[] target) {
     return sample(source, k, target, r);
   }
 
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static int[] sample(int[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static long[] sample(long[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static short[] sample(short[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static byte[] sample(byte[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static double[] sample(double[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static float[] sample(float[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static char[] sample(char[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source String with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The String from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length() * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static char[] sample(String source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length(), p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @param <T> The type of array elements.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static <T> T[] sample(T[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
   /**
    * Generates a random sample of k elements, without replacement, from a given source array. All n
    * choose k combinations are equally likely, where n is the length of the source array.

src/main/java/org/cicirello/sequences/SequenceInsertionSampler.java

@@ -23,6 +23,7 @@
 
 import java.util.random.RandomGenerator;
 import org.cicirello.math.rand.RandomSampler;
+import org.cicirello.math.rand.RandomVariates;
 import org.cicirello.util.ArrayMinimumLengthEnforcer;
 
 /**
@@ -157,6 +158,133 @@ public <T> T[] nextSample(T[] source, int k, T[] target) {
     return sample(source, k, target, r);
   }
 
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static int[] sample(int[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static long[] sample(long[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static short[] sample(short[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static byte[] sample(byte[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static double[] sample(double[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static float[] sample(float[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static char[] sample(char[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source String with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The String from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length() * p.
+   * @param r The source of randomness.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static char[] sample(String source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length(), p), null, r);
+  }
+
+  /**
+   * Generates a random sample, without replacement, from a given source array with a specified
+   * probability of an element's inclusion in the sample.
+   *
+   * @param source The array from which to sample.
+   * @param p The probability that element is included in the sample. The expected sample size is
+   *     source.length * p.
+   * @param r The source of randomness.
+   * @param <T> The type of array elements.
+   * @return An array containing the sample, whose sample size is simply the length of the array.
+   */
+  public static <T> T[] sample(T[] source, double p, RandomGenerator r) {
+    return sample(source, RandomVariates.nextBinomial(source.length, p), null, r);
+  }
+
   /**
    * Generates a random sample of k elements, without replacement, from a given source array. All n
    * choose k combinations are equally likely, where n is the length of the source array.