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(List<T> items, SharedStateDiscreteSampler sampler)
      Parameters:
      items - Collection to be sampled.
      sampler - Sampler for the probabilities.

  • 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

    • createSampler

      private static <T> SharedStateDiscreteSampler createSampler(UniformRandomProvider rng, List<T> collection, double[] probabilities)
      Creates the sampler of the enumerated probability distribution.
      Type Parameters:
      T - Type of items in the collection.
      Parameters:
      rng - Generator of uniformly distributed random numbers.
      collection - Collection to be sampled.
      probabilities - Probability associated to each item.
      Returns:
      the sampler
      Throws:
      IllegalArgumentException - if the number of items in the collection is not equal to the number of provided probabilities.

    • toList

      private static <T> List<T> toList(Map<T,Double> collection)
      Extract the items.
      Type Parameters:
      T - Type of items in the collection.
      Parameters:
      collection - Collection.
      Returns:
      the items
      Throws:
      IllegalArgumentException - if collection is empty.

    • toProbabilities

      private static <T> double[] toProbabilities(Map<T,Double> collection)
      Extract the probabilities.
      Type Parameters:
      T - Type of items in the collection.
      Parameters:
      collection - Collection.
      Returns:
      the probabilities

    • copyList

      private static <T> List<T> copyList(List<T> collection)
      Create a (shallow) copy of the collection.
      Type Parameters:
      T - Type of items in the collection.
      Parameters:
      collection - Collection.
      Returns:
      the copy
      Throws:
      IllegalArgumentException - if collection is empty.