Class EnumeratedDistribution<T>
- Type Parameters:
T
- type of the elements in the sample space.
- All Implemented Interfaces:
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 invalid input: '<'value, probability> 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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final double[]
Cumulative probabilities, cached to speed up sampling.private final double[]
Probabilities of respective random variable values.protected final RandomGenerator
RNG instance used to generate samples from the distribution.private static final long
Serializable UID.List of random variable values. -
Constructor Summary
ConstructorsConstructorDescriptionEnumeratedDistribution
(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
Modifier and TypeMethodDescriptiongetPmf()
Return the probability mass function as a list of invalid input: '<'value, probability> pairs.(package private) double
probability
(T x) For a random variableX
whose values are distributed according to this distribution, this method returnsP(X = x)
.void
reseedRandomGenerator
(long seed) Reseed the random generator used to generate samples.sample()
Generate a random value sampled from this distribution.Object[]
sample
(int sampleSize) Generate a random sample from the distribution.T[]
Generate a random sample from the distribution.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDSerializable UID.- See Also:
-
random
RNG instance used to generate samples from the distribution. -
singletons
List of random variable values. -
probabilities
private final double[] probabilitiesProbabilities 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[] cumulativeProbabilitiesCumulative probabilities, cached to speed up sampling.
-
-
Constructor Details
-
EnumeratedDistribution
public EnumeratedDistribution(List<Pair<T, Double>> pmf) throws NotPositiveException, MathArithmeticException, NotFiniteNumberException, NotANumberExceptionCreate 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 (seesample()
andsample(int)
). In case no sampling is needed for the created distribution, it is advised to passnull
as random generator via the appropriate constructors to avoid the additional initialisation overhead.- Parameters:
pmf
- probability mass function enumerated as a list of invalid input: '<'T, probability> 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, NotANumberExceptionCreate 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 invalid input: '<'T, probability> 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 Details
-
reseedRandomGenerator
public void reseedRandomGenerator(long seed) Reseed the random generator used to generate samples.- Parameters:
seed
- the new seed
-
probability
For a random variable
X
whose values are distributed according to this distribution, this method returnsP(X = x)
. In other words, this method represents the probability mass function (PMF) for the distribution.Note that if
x1
andx2
satisfyx1.equals(x2)
, or both are null, thenprobability(x1) = probability(x2)
.- Parameters:
x
- the point at which the PMF is evaluated- Returns:
- the value of the probability mass function at
x
-
getPmf
Return the probability mass function as a list of invalid input: '<'value, probability> 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
Generate a random value sampled from this distribution.- Returns:
- a random value.
-
sample
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
- ifsampleSize
is not positive.
-
sample
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
- ifsampleSize
is not positive.NullArgumentException
- ifarray
is null
-