java.lang.Object
org.cicirello.sequences.SequenceReservoirSampler
 All Implemented Interfaces:
SequenceSampler
SequenceReservoirSampler generates random samples of array elements, without replacement.
The methods of this class use the reservoir sampling algorithm (Algorithm R) from J. Vitter's 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software.
The runtime of the sample methods is O(n) and it generates O(nk) random numbers. Thus, it is an especially good choice as k approaches n. Only constant extra space required.

Constructor Summary
ConstructorDescriptionConstructs a sampler wrapping a RandomGenerator used as the source of randomness. 
Method Summary
Modifier and TypeMethodDescriptionbyte[]
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

SequenceReservoirSampler
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 interfaceSequenceSampler
 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.lengthNegativeArraySizeException
 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 interfaceSequenceSampler
 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.lengthNegativeArraySizeException
 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 interfaceSequenceSampler
 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.lengthNegativeArraySizeException
 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 interfaceSequenceSampler
 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.lengthNegativeArraySizeException
 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 interfaceSequenceSampler
 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.lengthNegativeArraySizeException
 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 interfaceSequenceSampler
 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.lengthNegativeArraySizeException
 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 interfaceSequenceSampler
 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.lengthNegativeArraySizeException
 if k < 0

nextSample
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 interfaceSequenceSampler
 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 interfaceSequenceSampler
 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.lengthNegativeArraySizeException
 if k < 0

sample
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
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
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
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
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
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
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
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
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
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.lengthNegativeArraySizeException
 if k < 0

sample
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.lengthNegativeArraySizeException
 if k < 0

sample
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.lengthNegativeArraySizeException
 if k < 0

sample
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.lengthNegativeArraySizeException
 if k < 0

sample
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.lengthNegativeArraySizeException
 if k < 0

sample
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
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.lengthNegativeArraySizeException
 if k < 0

sample
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.lengthNegativeArraySizeException
 if k < 0

sample
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.lengthNegativeArraySizeException
 if k < 0
