Class SequenceInsertionSampler

java.lang.Object
org.cicirello.sequences.SequenceInsertionSampler
All Implemented Interfaces:
SequenceSampler

public final class SequenceInsertionSampler extends Object implements SequenceSampler
SequenceInsertionSampler generates random samples of array elements, without replacement.

The methods of this class implement the insertion sampling algorithm 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 the sample methods is O(k2) and generates O(k) random numbers. Thus, it is a better choice than both SequenceReservoirSampler and SequencePoolSampler when k2 < n. Just like SequenceReservoirSampler, the SequenceInsertionSampler only requires O(1) extra space, while SequencePoolSampler requires O(n) extra space.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a sampler wrapping a RandomGenerator used as the source of randomness.
  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    nextSample(byte[] source, int k, byte[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    char[]
    nextSample(char[] source, int k, char[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    double[]
    nextSample(double[] source, int k, double[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    float[]
    nextSample(float[] source, int k, float[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    int[]
    nextSample(int[] source, int k, int[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    long[]
    nextSample(long[] source, int k, long[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    short[]
    nextSample(short[] source, int k, short[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    char[]
    nextSample(String source, int k, char[] target)
    Generates a random sample of k elements, without replacement, from a given source String.
    <T> T[]
    nextSample(T[] source, int k, T[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static byte[]
    sample(byte[] source, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    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, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    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, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    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, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    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, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    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, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    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, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    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, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source String with a specified probability of an element's inclusion in the sample.
    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, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    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

    Methods inherited from interface org.cicirello.sequences.SequenceSampler

    nextSample, nextSample, nextSample, nextSample, nextSample, nextSample, nextSample, nextSample, nextSample
  • Constructor Details

    • SequenceInsertionSampler

      public SequenceInsertionSampler(RandomGenerator r)
      Constructs a sampler wrapping a RandomGenerator used as the source of randomness.
      Parameters:
      r - The source of randomness.
  • Method Details

    • nextSample

      public int[] nextSample(int[] source, int k, int[] target)
      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.
      Specified by:
      nextSample in interface SequenceSampler
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0
    • nextSample

      public long[] nextSample(long[] source, int k, long[] target)
      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.
      Specified by:
      nextSample in interface SequenceSampler
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0
    • nextSample

      public short[] nextSample(short[] source, int k, short[] target)
      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.
      Specified by:
      nextSample in interface SequenceSampler
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0
    • nextSample

      public byte[] nextSample(byte[] source, int k, byte[] target)
      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.
      Specified by:
      nextSample in interface SequenceSampler
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0
    • nextSample

      public double[] nextSample(double[] source, int k, double[] target)
      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.
      Specified by:
      nextSample in interface SequenceSampler
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0
    • nextSample

      public float[] nextSample(float[] source, int k, float[] target)
      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.
      Specified by:
      nextSample in interface SequenceSampler
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0
    • nextSample

      public char[] nextSample(char[] source, int k, char[] target)
      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.
      Specified by:
      nextSample in interface SequenceSampler
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0
    • nextSample

      public char[] nextSample(String source, int k, char[] target)
      Generates a random sample of k elements, without replacement, from a given source String. All n choose k combinations are equally likely, where n is the length of the source String.
      Specified by:
      nextSample in interface SequenceSampler
      Parameters:
      source - The source String 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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length()
      NegativeArraySizeException - if k < 0
    • nextSample

      public <T> T[] nextSample(T[] source, int k, T[] target)
      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.
      Specified by:
      nextSample in interface SequenceSampler
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0
    • sample

      public static int[] sample(int[] source, double p, RandomGenerator r)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.
    • sample

      public static long[] sample(long[] source, double p, RandomGenerator r)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.
    • sample

      public static short[] sample(short[] source, double p, RandomGenerator r)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.
    • sample

      public static byte[] sample(byte[] source, double p, RandomGenerator r)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.
    • sample

      public static double[] sample(double[] source, double p, RandomGenerator r)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.
    • sample

      public static float[] sample(float[] source, double p, RandomGenerator r)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.
    • sample

      public static char[] sample(char[] source, double p, RandomGenerator r)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.
    • sample

      public static char[] sample(String source, double p, RandomGenerator r)
      Generates a random sample, without replacement, from a given source String with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The String from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length() * p.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.
    • sample

      public static <T> T[] sample(T[] source, double p, RandomGenerator r)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.
    • 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 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