Module org.cicirello.jpt
Package org.cicirello.sequences

Class SequenceCompositeSampler

java.lang.Object
org.cicirello.sequences.SequenceCompositeSampler
public final class SequenceCompositeSampler extends Object
SequenceCompositeSampler is a class of utility methods for efficiently generating random samples of array elements, without replacement.

This class implements the composite sampler that combines reservoir sampling, pool sampling, and insertion sampling as described in:

Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

The runtime of this approach is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers. This derives from its choice from among the approaches of SequenceReservoirSampler, SequencePoolSampler, and SequenceInsertionSampler.

  • Method Summary

    Modifier and Type
    Method
    Description
    static byte[]
    sample(byte[] source, int k, byte[] target, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static char[]
    sample(char[] source, int k, char[] target, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static double[]
    sample(double[] source, int k, double[] target, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static float[]
    sample(float[] source, int k, float[] target, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static int[]
    sample(int[] source, int k, int[] target, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static long[]
    sample(long[] source, int k, long[] target, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static short[]
    sample(short[] source, int k, short[] target, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static char[]
    sample(String source, int k, char[] target, RandomGenerator r)
    Generates a random sample of k chars, without replacement, from a given source String.
    static <T> T[]
    sample(T[] source, int k, T[] target, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • sample

      public static int[] sample(int[] source, int k, int[] target, RandomGenerator 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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static long[] sample(long[] source, int k, long[] target, RandomGenerator 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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static short[] sample(short[] source, int k, short[] target, RandomGenerator 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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static byte[] sample(byte[] source, int k, byte[] target, RandomGenerator 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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static char[] sample(char[] source, int k, char[] target, RandomGenerator 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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static char[] sample(String source, int k, char[] target, RandomGenerator r)
      Generates a random sample of k chars, without replacement, from a given source String. All n choose k combinations are equally likely, where n is the length of the source String.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length()).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length()
      NegativeArraySizeException - if k < 0

    • sample

      public static double[] sample(double[] source, int k, double[] target, RandomGenerator 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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static float[] sample(float[] source, int k, float[] target, RandomGenerator 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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static <T> T[] sample(T[] source, int k, T[] target, RandomGenerator 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.
      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      target - An array to hold the result. If target is null or target.length is less than k, then this method will construct a new array for the result.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0