Class EnumeratedDistribution<T>

  • Type Parameters:
    T - type of the elements in the sample space.
    All Implemented Interfaces:
    java.io.Serializable

    public class EnumeratedDistribution<T>
    extends java.lang.Object
    implements java.io.Serializable

    A generic implementation of a discrete probability distribution (Wikipedia) over a finite sample space, based on an enumerated list of <value, probability> pairs. Input probabilities must all be non-negative, but zero values are allowed and their sum does not have to equal one. Constructors will normalize input probabilities to make them sum to one.

    The list of pairs does not, strictly speaking, have to be a function and it can contain null values. The pmf created by the constructor will combine probabilities of equal values and will treat null values as equal. For example, if the list of pairs <"dog", 0.2>, <null, 0.1>, <"pig", 0.2>, <"dog", 0.1>, <null, 0.4> is provided to the constructor, the resulting pmf will assign mass of 0.5 to null, 0.3 to "dog" and 0.2 to null.

    Since:
    3.2
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private double[] cumulativeProbabilities
      Cumulative probabilities, cached to speed up sampling.
      private double[] probabilities
      Probabilities of respective random variable values.
      protected RandomGenerator random
      RNG instance used to generate samples from the distribution.
      private static long serialVersionUID
      Serializable UID.
      private java.util.List<T> singletons
      List of random variable values.
    • Constructor Summary

      Constructors 
      Constructor Description
      EnumeratedDistribution​(java.util.List<Pair<T,​java.lang.Double>> pmf)
      Create an enumerated distribution using the given probability mass function enumeration.
      EnumeratedDistribution​(RandomGenerator rng, java.util.List<Pair<T,​java.lang.Double>> pmf)
      Create an enumerated distribution using the given random number generator and probability mass function enumeration.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.List<Pair<T,​java.lang.Double>> getPmf()
      Return the probability mass function as a list of pairs.
      (package private) double probability​(T x)
      For a random variable X whose values are distributed according to this distribution, this method returns P(X = x).
      void reseedRandomGenerator​(long seed)
      Reseed the random generator used to generate samples.
      T sample()
      Generate a random value sampled from this distribution.
      java.lang.Object[] sample​(int sampleSize)
      Generate a random sample from the distribution.
      T[] sample​(int sampleSize, T[] array)
      Generate a random sample from the distribution.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        Serializable UID.
        See Also:
        Constant Field Values
      • random

        protected final RandomGenerator random
        RNG instance used to generate samples from the distribution.
      • singletons

        private final java.util.List<T> singletons
        List of random variable values.
      • probabilities

        private final double[] probabilities
        Probabilities of respective random variable values. For i = 0, ..., singletons.size() - 1, probability[i] is the probability that a random variable following this distribution takes the value singletons[i].
      • cumulativeProbabilities

        private final double[] cumulativeProbabilities
        Cumulative probabilities, cached to speed up sampling.
    • Method Detail

      • reseedRandomGenerator

        public void reseedRandomGenerator​(long seed)
        Reseed the random generator used to generate samples.
        Parameters:
        seed - the new seed
      • probability

        double probability​(T x)

        For a random variable X whose values are distributed according to this distribution, this method returns P(X = x). In other words, this method represents the probability mass function (PMF) for the distribution.

        Note that if x1 and x2 satisfy x1.equals(x2), or both are null, then probability(x1) = probability(x2).

        Parameters:
        x - the point at which the PMF is evaluated
        Returns:
        the value of the probability mass function at x
      • getPmf

        public java.util.List<Pair<T,​java.lang.Double>> getPmf()

        Return the probability mass function as a list of pairs.

        Note that if duplicate and / or null values were provided to the constructor when creating this EnumeratedDistribution, the returned list will contain these values. If duplicates values exist, what is returned will not represent a pmf (i.e., it is up to the caller to consolidate duplicate mass points).

        Returns:
        the probability mass function.
      • sample

        public T sample()
        Generate a random value sampled from this distribution.
        Returns:
        a random value.
      • sample

        public java.lang.Object[] sample​(int sampleSize)
                                  throws NotStrictlyPositiveException
        Generate a random sample from the distribution.
        Parameters:
        sampleSize - the number of random values to generate.
        Returns:
        an array representing the random sample.
        Throws:
        NotStrictlyPositiveException - if sampleSize is not positive.
      • sample

        public T[] sample​(int sampleSize,
                          T[] array)
                   throws NotStrictlyPositiveException
        Generate a random sample from the distribution.

        If the requested samples fit in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

        Parameters:
        sampleSize - the number of random values to generate.
        array - the array to populate.
        Returns:
        an array representing the random sample.
        Throws:
        NotStrictlyPositiveException - if sampleSize is not positive.
        NullArgumentException - if array is null