Package org.apache.commons.math3.distribution

Class AbstractIntegerDistribution

java.lang.Object

org.apache.commons.math3.distribution.AbstractIntegerDistribution

All Implemented Interfaces:

java.io.Serializable, IntegerDistribution

Direct Known Subclasses:

BinomialDistribution, EnumeratedIntegerDistribution, GeometricDistribution, HypergeometricDistribution, PascalDistribution, PoissonDistribution, UniformIntegerDistribution, ZipfDistribution

public abstract class AbstractIntegerDistribution
extends java.lang.Object
implements IntegerDistribution, java.io.Serializable

Base class for integer-valued discrete distributions. Default implementations are provided for some of the methods that do not vary from distribution to distribution.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
protected RandomGenerator	random	RNG instance used to generate samples from the distribution.
protected RandomDataImpl	randomData	Deprecated. As of 3.1, to be removed in 4.0.
private static long	serialVersionUID	Serializable version identifier

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractIntegerDistribution()	Deprecated. As of 3.1, to be removed in 4.0.
protected	AbstractIntegerDistribution(RandomGenerator rng)

Method Summary

Modifier and Type	Method	Description
private double	checkedCumulativeProbability(int argument)	Computes the cumulative probability function and checks for NaN values returned.
double	cumulativeProbability(int x0, int x1)	For a random variable X whose values are distributed according to this distribution, this method returns P(x0 < X <= x1).
int	inverseCumulativeProbability(double p)	Computes the quantile function of this distribution.
double	logProbability(int x)	For a random variable X whose values are distributed according to this distribution, this method returns log(P(X = x)), where log is the natural logarithm.
void	reseedRandomGenerator(long seed)	Reseed the random generator used to generate samples.
int	sample()	Generate a random value sampled from this distribution.
int[]	sample(int sampleSize)	Generate a random sample from the distribution.
protected int	solveInverseCumulativeProbability(double p, int lower, int upper)	This is a utility function used by inverseCumulativeProbability(double).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.commons.math3.distribution.IntegerDistribution

cumulativeProbability, getNumericalMean, getNumericalVariance, getSupportLowerBound, getSupportUpperBound, isSupportConnected, probability

Field Detail

serialVersionUID

private static final long serialVersionUID

Serializable version identifier

See Also:

Constant Field Values

randomData

@Deprecated
protected final RandomDataImpl randomData

Deprecated.

As of 3.1, to be removed in 4.0. Please use the random instance variable instead.

RandomData instance used to generate samples from the distribution.

random

protected final RandomGenerator random

RNG instance used to generate samples from the distribution.

Since:

3.1

Constructor Detail

AbstractIntegerDistribution

@Deprecated
protected AbstractIntegerDistribution()

Deprecated.

As of 3.1, to be removed in 4.0. Please use AbstractIntegerDistribution(RandomGenerator) instead.

AbstractIntegerDistribution

protected AbstractIntegerDistribution(RandomGenerator rng)

Parameters:

rng - Random number generator.

Since:

3.1

Method Detail

cumulativeProbability

public double cumulativeProbability(int x0,
                                    int x1)
                             throws NumberIsTooLargeException

For a random variable X whose values are distributed according to this distribution, this method returns P(x0 < X <= x1). The default implementation uses the identity

P(x0 < X <= x1) = P(X <= x1) - P(X <= x0)

Specified by:

cumulativeProbability in interface IntegerDistribution

Parameters:

x0 - the exclusive lower bound

x1 - the inclusive upper bound

Returns:

the probability that a random variable with this distribution will take a value between x0 and x1, excluding the lower and including the upper endpoint

Throws:

NumberIsTooLargeException - if x0 > x1

inverseCumulativeProbability

public int inverseCumulativeProbability(double p)
                                 throws OutOfRangeException

Computes the quantile function of this distribution. For a random variable X distributed according to this distribution, the returned value is

• inf{x in Z | P(X<=x) >= p} for 0 < p <= 1,
• inf{x in Z | P(X<=x) > 0} for p = 0.

If the result exceeds the range of the data type int, then Integer.MIN_VALUE or Integer.MAX_VALUE is returned. The default implementation returns

• IntegerDistribution.getSupportLowerBound() for p = 0,
• IntegerDistribution.getSupportUpperBound() for p = 1, and
• solveInverseCumulativeProbability(double, int, int) for 0 < p < 1.

Specified by:

inverseCumulativeProbability in interface IntegerDistribution

Parameters:

p - the cumulative probability

Returns:

the smallest p-quantile of this distribution (largest 0-quantile for p = 0)

Throws:

OutOfRangeException - if p < 0 or p > 1

solveInverseCumulativeProbability

protected int solveInverseCumulativeProbability(double p,
                                                int lower,
                                                int upper)

This is a utility function used by inverseCumulativeProbability(double). It assumes 0 < p < 1 and that the inverse cumulative probability lies in the bracket (lower, upper]. The implementation does simple bisection to find the smallest p-quantile inf{x in Z | P(X<=x) >= p}.

Parameters:

p - the cumulative probability

lower - a value satisfying cumulativeProbability(lower) < p

upper - a value satisfying p <= cumulativeProbability(upper)

Returns:

the smallest p-quantile of this distribution

reseedRandomGenerator

public void reseedRandomGenerator(long seed)

Reseed the random generator used to generate samples.

Specified by:

reseedRandomGenerator in interface IntegerDistribution

Parameters:

seed - the new seed

sample

public int sample()

Generate a random value sampled from this distribution. The default implementation uses the inversion method.

Specified by:

sample in interface IntegerDistribution

Returns:

a random value

sample

public int[] sample(int sampleSize)

Generate a random sample from the distribution. The default implementation generates the sample by calling sample() in a loop.

Specified by:

sample in interface IntegerDistribution

Parameters:

sampleSize - the number of random values to generate

Returns:

an array representing the random sample

checkedCumulativeProbability

private double checkedCumulativeProbability(int argument)
                                     throws MathInternalError

Computes the cumulative probability function and checks for NaN values returned. Throws MathInternalError if the value is NaN. Rethrows any exception encountered evaluating the cumulative probability function. Throws MathInternalError if the cumulative probability function returns NaN.

Parameters:

argument - input value

Returns:

the cumulative probability

Throws:

MathInternalError - if the cumulative probability is NaN

logProbability

public double logProbability(int x)

For a random variable X whose values are distributed according to this distribution, this method returns log(P(X = x)), where log is the natural logarithm. In other words, this method represents the logarithm of the probability mass function (PMF) for the distribution. Note that due to the floating point precision and under/overflow issues, this method will for some distributions be more precise and faster than computing the logarithm of IntegerDistribution.probability(int).

The default implementation simply computes the logarithm of probability(x).

Parameters:

x - the point at which the PMF is evaluated

Returns:

the logarithm of the value of the probability mass function at x