Package org.apache.commons.rng.sampling

Class DiscreteProbabilityCollectionSampler<T>

java.lang.Object

org.apache.commons.rng.sampling.DiscreteProbabilityCollectionSampler<T>

Type Parameters:

T - Type of items in the collection.

All Implemented Interfaces:

ObjectSampler<T>, SharedStateObjectSampler<T>, SharedStateSampler<SharedStateObjectSampler<T>>

public class DiscreteProbabilityCollectionSampler<T>
extends Object
implements SharedStateObjectSampler<T>

Sampling from a collection of items with user-defined probabilities. Note that if all unique items are assigned the same probability, it is much more efficient to use CollectionSampler.

Sampling uses UniformRandomProvider.nextDouble().

Since:

1.1

Constructor Summary

Constructors

Constructor	Description
DiscreteProbabilityCollectionSampler(UniformRandomProvider rng, List<T> collection, double[] probabilities)	Creates a sampler.
DiscreteProbabilityCollectionSampler(UniformRandomProvider rng, Map<T,Double> collection)	Creates a sampler.

Method Summary

Modifier and Type	Method	Description
T	sample()	Picks one of the items from the collection passed to the constructor.
DiscreteProbabilityCollectionSampler<T>	withUniformRandomProvider(UniformRandomProvider rng)	Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.

Methods inherited from class java.lang.Object

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

Constructor Detail

DiscreteProbabilityCollectionSampler

public DiscreteProbabilityCollectionSampler(UniformRandomProvider rng,
                                            Map<T,Double> collection)

Creates a sampler.

Parameters:

rng - Generator of uniformly distributed random numbers.

collection - Collection to be sampled, with the probabilities associated to each of its items. A (shallow) copy of the items will be stored in the created instance. The probabilities must be non-negative, but zero values are allowed and their sum does not have to equal one (input will be normalized to make the probabilities sum to one).

Throws:

IllegalArgumentException - if collection is empty, a probability is negative, infinite or NaN, or the sum of all probabilities is not strictly positive.

DiscreteProbabilityCollectionSampler

public DiscreteProbabilityCollectionSampler(UniformRandomProvider rng,
                                            List<T> collection,
                                            double[] probabilities)

Creates a sampler.

Parameters:

rng - Generator of uniformly distributed random numbers.

collection - Collection to be sampled. A (shallow) copy of the items will be stored in the created instance.

probabilities - Probability associated to each item of the collection. The probabilities must be non-negative, but zero values are allowed and their sum does not have to equal one (input will be normalized to make the probabilities sum to one).

Throws:

IllegalArgumentException - if collection is empty or a probability is negative, infinite or NaN, or if the number of items in the collection is not equal to the number of provided probabilities.

Method Detail

sample

public T sample()

Picks one of the items from the collection passed to the constructor.

Specified by:

sample in interface ObjectSampler<T>

Returns:

a random sample.

withUniformRandomProvider

public DiscreteProbabilityCollectionSampler<T> withUniformRandomProvider(UniformRandomProvider rng)

Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.

Specified by:

withUniformRandomProvider in interface SharedStateSampler<T>

Parameters:

rng - Generator of uniformly distributed random numbers.

Returns:

the sampler

Since:

1.3