EnumeratedDistribution (Apache Commons Math 3.6.1 API)

org.apache.commons.math3.distribution

## Class EnumeratedDistribution<T>

- java.lang.Object
- - org.apache.commons.math3.distribution.EnumeratedDistribution<T>

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

      public class EnumeratedDistribution<T>
      extends Object
      implements 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 and Description
    --- | ---
    `protected RandomGenerator` | `random` RNG instance used to generate samples from the distribution.

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `List<Pair<T,Double>>` | `getPmf()` Return the probability mass function as a list of pairs.
    `void` | `reseedRandomGenerator(long seed)` Reseed the random generator used to generate samples.
    `T` | `sample()` Generate a random value sampled from this distribution.
    `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

    - #### random

          protected final RandomGenerator random

      RNG instance used to generate samples from the distribution.

  - ### Constructor Detail

    - #### EnumeratedDistribution

          public EnumeratedDistribution(List<Pair<T,Double>> pmf)
                                 throws NotPositiveException,
                                        MathArithmeticException,
                                        NotFiniteNumberException,
                                        NotANumberException

      Create an enumerated distribution using the given probability mass function enumeration.

      Note: this constructor will implicitly create an instance of `Well19937c` as random generator to be used for sampling only (see `sample()` and `sample(int)`). In case no sampling is needed for the created distribution, it is advised to pass `null` as random generator via the appropriate constructors to avoid the additional initialisation overhead.

      Parameters:
        `pmf` - probability mass function enumerated as a list of pairs.
      Throws:
        `NotPositiveException` - if any of the probabilities are negative.
        `NotFiniteNumberException` - if any of the probabilities are infinite.
        `NotANumberException` - if any of the probabilities are NaN.
        `MathArithmeticException` - all of the probabilities are 0.

    - #### EnumeratedDistribution

          public EnumeratedDistribution(RandomGenerator rng,
                                List<Pair<T,Double>> pmf)
                                 throws NotPositiveException,
                                        MathArithmeticException,
                                        NotFiniteNumberException,
                                        NotANumberException

      Create an enumerated distribution using the given random number generator and probability mass function enumeration.
      Parameters:
        `rng` - random number generator.
        `pmf` - probability mass function enumerated as a list of pairs.
      Throws:
        `NotPositiveException` - if any of the probabilities are negative.
        `NotFiniteNumberException` - if any of the probabilities are infinite.
        `NotANumberException` - if any of the probabilities are NaN.
        `MathArithmeticException` - all of the probabilities are 0.

  - ### Method Detail

    - #### reseedRandomGenerator

          public void reseedRandomGenerator(long seed)

      Reseed the random generator used to generate samples.
      Parameters:
        `seed` - the new seed

    - #### getPmf

          public List<Pair<T,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 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

Copyright © 2003–2016 The Apache Software Foundation. All rights reserved.