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
  • Field Details

    • EMPTY_COLLECTION

      private static final String EMPTY_COLLECTION
      The error message for an empty collection.
      See Also:
    • items

      private final List<T> items
      Collection to be sampled from.
    • sampler

      private final SharedStateDiscreteSampler sampler
      Sampler for the probabilities.
  • Constructor Details

    • 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.
    • DiscreteProbabilityCollectionSampler

      private DiscreteProbabilityCollectionSampler(UniformRandomProvider rng, DiscreteProbabilityCollectionSampler<T> source)
      Parameters:
      rng - Generator of uniformly distributed random numbers.
      source - Source to copy.
  • Method Details

    • 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
    • createSampler

      private static SharedStateDiscreteSampler createSampler(UniformRandomProvider rng, double[] probabilities)
      Creates the sampler of the enumerated probability distribution.
      Parameters:
      rng - Generator of uniformly distributed random numbers.
      probabilities - Probability associated to each item.
      Returns:
      the sampler