gov.sandia.cognition.statistics
Class DiscreteSamplingUtil

java.lang.Object
  extended by gov.sandia.cognition.statistics.DiscreteSamplingUtil

public class DiscreteSamplingUtil
extends Object

A utility class for sampling.

Since:
3.1
Author:
Justin Basilico

Constructor Summary
DiscreteSamplingUtil()
           
 
Method Summary
static int sampleIndexFromCumulativeProportions(Random random, double[] cumulativeProportions)
          Samples a random index from an array of cumulative proportions.
static int sampleIndexFromProbabilities(Random random, double[] probabilities)
          Samples an random index according to the given array of probabilities.
static int sampleIndexFromProbabilities(Random random, Vector probabilities)
          Samples an random index according to the given vector of probabilities.
static int sampleIndexFromProportions(Random random, double[] proportions)
          Samples a random index according to the given proportions.
static int sampleIndexFromProportions(Random random, double[] proportions, double proportionSum)
          Samples a random index according to the given proportions.
static int[] sampleIndicesFromCumulativeProportions(Random random, double[] cumulativeProportions, int sampleSize)
          Samples a multiple indices with replacement from an array of cumulative proportions.
static int[] sampleIndicesFromProportions(Random random, double[] proportions, int sampleSize)
          Samples an array of indices from a given set of proportions.
static
<DataType> List<DataType>
sampleWithoutReplacement(Random random, List<DataType> data, int sampleSize)
          Samples a a given number of items from a list without replacement.
static
<DataType> ArrayList<DataType>
sampleWithReplacement(Random random, List<? extends DataType> data, int sampleSize)
          Samples a a given number of items from a list with replacement.
static
<DataType> void
sampleWithReplacementInto(Random random, List<? extends DataType> data, int sampleSize, Collection<? super DataType> result)
          Samples a a given number of items from a list with replacement and puts the samples into the given collection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DiscreteSamplingUtil

public DiscreteSamplingUtil()
Method Detail

sampleIndexFromProbabilities

public static int sampleIndexFromProbabilities(Random random,
                                               double[] probabilities)
Samples an random index according to the given array of probabilities.

Parameters:
random - The random number generator to use.
probabilities - The array of probabilities. Must sum to 1.0.
Returns:
A random index sampled according to the given probabilities.

sampleIndexFromProbabilities

public static int sampleIndexFromProbabilities(Random random,
                                               Vector probabilities)
Samples an random index according to the given vector of probabilities.

Parameters:
random - The random number generator to use.
probabilities - The vector of probabilities. Must sum to 1.0.
Returns:
A random index sampled according to the given probabilities.

sampleIndexFromProportions

public static int sampleIndexFromProportions(Random random,
                                             double[] proportions)
Samples a random index according to the given proportions. Note that calling this requires calculating the sum of the proportions first, so if it is known in advance, it is more efficient to call the version of this method that takes the sum of the proportions as a parameter.

Parameters:
random - The random number generator to use.
proportions - The array of proportions. All entries must be greater than or equal to zero.
Returns:
A random index sampled according to the given proportions.

sampleIndicesFromProportions

public static int[] sampleIndicesFromProportions(Random random,
                                                 double[] proportions,
                                                 int sampleSize)
Samples an array of indices from a given set of proportions.

Parameters:
random - The random number generator to use.
proportions - The array of proportions. All entries must be greater than or equal to zero.
sampleSize - The number of samples to make.
Returns:
A an array of random indices sampled according to the given proportions.

sampleIndexFromProportions

public static int sampleIndexFromProportions(Random random,
                                             double[] proportions,
                                             double proportionSum)
Samples a random index according to the given proportions. Note that sampling according cumulative proportions may be slightly faster than this method.

Parameters:
random - The random number generator to use.
proportions - An array of proportions. None of the entries can be negative. It must sum to proportionSum.
proportionSum - The sum of the given proportions array.
Returns:
An index sampled at random from the given proportions array, according to those proportions.

sampleIndexFromCumulativeProportions

public static int sampleIndexFromCumulativeProportions(Random random,
                                                       double[] cumulativeProportions)
Samples a random index from an array of cumulative proportions.

Parameters:
random - The random number generator to use.
cumulativeProportions - The array of cumulative proportions. The entries must be non-negative and monotonically increasing.
Returns:
An index of the given array samples at random according to the given cumulative proportions.

sampleIndicesFromCumulativeProportions

public static int[] sampleIndicesFromCumulativeProportions(Random random,
                                                           double[] cumulativeProportions,
                                                           int sampleSize)
Samples a multiple indices with replacement from an array of cumulative proportions.

Parameters:
random - The random number generator to use.
cumulativeProportions - The array of cumulative proportions. The entries must be non-negative and monotonically increasing.
sampleSize - The number of samples to draw from the cumulative proportions.
Returns:
An array of indices of sampled with replacement according to the given cumulative proportions.

sampleWithReplacement

public static <DataType> ArrayList<DataType> sampleWithReplacement(Random random,
                                                                   List<? extends DataType> data,
                                                                   int sampleSize)
Samples a a given number of items from a list with replacement.

Type Parameters:
DataType - The type of data in the list.
Parameters:
random - The random number generator.
data - The list to sample from.
sampleSize - The sample size. Must be positive.
Returns:
An array list of the given size sampled with replacement from the given data.

sampleWithReplacementInto

public static <DataType> void sampleWithReplacementInto(Random random,
                                                        List<? extends DataType> data,
                                                        int sampleSize,
                                                        Collection<? super DataType> result)
Samples a a given number of items from a list with replacement and puts the samples into the given collection.

Type Parameters:
DataType - The type of data in the list.
Parameters:
random - The random number generator.
data - The list to sample from.
sampleSize - The sample size. Must be positive.
result - The resulting collection to sample into. All sampled elements will be added to this collection..

sampleWithoutReplacement

public static <DataType> List<DataType> sampleWithoutReplacement(Random random,
                                                                 List<DataType> data,
                                                                 int sampleSize)
Samples a a given number of items from a list without replacement.

Type Parameters:
DataType - The type of data in the list.
Parameters:
random - The random number generator.
data - The list to sample from.
sampleSize - The sample size. Must be positive and less than or equal to the data size.
Returns:
A list sampled without replacement from the given data. It will be of size sampleSize.