Top Description Fields Constructors Methods
org.apache.commons.math3.distribution

public Class PoissonDistribution

extends AbstractIntegerDistribution
Class Inheritance
Imports
org.apache.commons.math3.exception.NotStrictlyPositiveException, org.apache.commons.math3.exception.util.LocalizedFormats, org.apache.commons.math3.random.RandomGenerator, .Well19937c, org.apache.commons.math3.special.Gamma, org.apache.commons.math3.util.CombinatoricsUtils, .FastMath, .MathUtils
Implementation of the Poisson distribution.
See Also
Poisson distribution (Wikipedia), Poisson distribution (MathWorld)

Field Summary

Modifier and TypeField and Description
public static final double
DEFAULT_EPSILON

Default convergence criterion.

public static final int
DEFAULT_MAX_ITERATIONS

Default maximum number of iterations for cumulative probability calculations.

private final double
epsilon

Convergence criterion for cumulative probability.

private final ExponentialDistribution
exponential

Distribution needed for the sample() method.

private final int
maxIterations

Maximum number of iterations for cumulative probability.

private final double
mean

Mean of the distribution.

private final NormalDistribution
normal

Distribution used to compute normal approximation.

private static final long
serialVersionUID

Hides org.apache.commons.math3.distribution.AbstractIntegerDistribution.serialVersionUID.

Serializable version identifier.
Inherited from org.apache.commons.math3.distribution.AbstractIntegerDistribution:
randomrandomData

Constructor Summary

AccessConstructor and Description
public
PoissonDistribution(double
the Poisson mean
p)

Creates a new Poisson distribution with specified mean.

public
PoissonDistribution(double
Poisson mean.
p, double
Convergence criterion for cumulative probabilities.
epsilon, int
the maximum number of iterations for cumulative probabilities.
maxIterations)

Creates a new Poisson distribution with specified mean, convergence criterion and maximum number of iterations.

public
PoissonDistribution(RandomGenerator
Random number generator.
rng, double
Poisson mean.
p, double
Convergence criterion for cumulative probabilities.
epsilon, int
the maximum number of iterations for cumulative probabilities.
maxIterations)

Creates a new Poisson distribution with specified mean, convergence criterion and maximum number of iterations.

public
PoissonDistribution(double
Poisson mean.
p, double
Convergence criterion for cumulative probabilities.
epsilon)

Creates a new Poisson distribution with the specified mean and convergence criterion.

public
PoissonDistribution(double
Poisson mean.
p, int
Maximum number of iterations for cumulative probabilities.
maxIterations)

Creates a new Poisson distribution with the specified mean and maximum number of iterations.

Method Summary

Modifier and TypeMethod and Description
public double
cumulativeProbability(int
the point at which the CDF is evaluated
x)

Implements org.apache.commons.math3.distribution.IntegerDistribution.cumulativeProbability.

For a random variable X whose values are distributed according to this distribution, this method returns P(X <= x).

public double

Returns:

the mean for the distribution.
getMean()

Get the mean for the distribution.

public double
getNumericalMean()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalMean.

Use this method to get the numerical value of the mean of this distribution.

public double
getNumericalVariance()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalVariance.

Use this method to get the numerical value of the variance of this distribution.

public int

Returns:

lower bound of the support (always 0)
getSupportLowerBound()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportLowerBound.

Access the lower bound of the support.

public int

Returns:

upper bound of the support (always Integer.MAX_VALUE for positive infinity)
getSupportUpperBound()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportUpperBound.

Access the upper bound of the support.

public boolean

Returns:

true
isSupportConnected()

Implements org.apache.commons.math3.distribution.IntegerDistribution.isSupportConnected.

Use this method to get information about whether the support is connected, i.e. whether all integers between the lower and upper bound of the support are included in the support.

public double
logProbability(int
the point at which the PMF is evaluated
x)

Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.logProbability.

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.

private long

Returns:

the next sample.
nextPoisson(double
Mean of the Poisson distribution.
meanPoisson)

public double

Returns:

the distribution function value calculated using a normal approximation.
normalApproximateProbability(int
Upper bound, inclusive.
x)

Calculates the Poisson distribution function using a normal approximation.

public double
probability(int
the point at which the PMF is evaluated
x)

Implements org.apache.commons.math3.distribution.IntegerDistribution.probability.

For a random variable X whose values are distributed according to this distribution, this method returns P(X = x).

public int

Returns:

a random value.
sample()

Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.sample.

Implements org.apache.commons.math3.distribution.IntegerDistribution.sample.

Generate a random value sampled from this distribution.

Inherited from org.apache.commons.math3.distribution.AbstractIntegerDistribution:
cumulativeProbabilityinverseCumulativeProbabilityreseedRandomGeneratorsamplesolveInverseCumulativeProbability

Field Detail

DEFAULT_EPSILONback to summary
public static final double DEFAULT_EPSILON

Default convergence criterion.

Since
2.1
DEFAULT_MAX_ITERATIONSback to summary
public static final int DEFAULT_MAX_ITERATIONS

Default maximum number of iterations for cumulative probability calculations.

Since
2.1
epsilonback to summary
private final double epsilon

Convergence criterion for cumulative probability.

exponentialback to summary
private final ExponentialDistribution exponential

Distribution needed for the sample() method.

maxIterationsback to summary
private final int maxIterations

Maximum number of iterations for cumulative probability. Cumulative probabilities are estimated using either Lanczos series approximation of Gamma#regularizedGammaP(double, double, double, int) or continued fraction approximation of Gamma#regularizedGammaQ(double, double, double, int).

meanback to summary
private final double mean

Mean of the distribution.

normalback to summary
private final NormalDistribution normal

Distribution used to compute normal approximation.

serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.commons.math3.distribution.AbstractIntegerDistribution.serialVersionUID.

Serializable version identifier.

Constructor Detail

PoissonDistributionback to summary
public PoissonDistribution(double p) throws NotStrictlyPositiveException

Creates a new Poisson distribution with specified mean.

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
p:double

the Poisson mean

Exceptions
NotStrictlyPositiveException:
if p <= 0.
PoissonDistributionback to summary
public PoissonDistribution(double p, double epsilon, int maxIterations) throws NotStrictlyPositiveException

Creates a new Poisson distribution with specified mean, convergence criterion and maximum number of iterations.

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
p:double

Poisson mean.

epsilon:double

Convergence criterion for cumulative probabilities.

maxIterations:int

the maximum number of iterations for cumulative probabilities.

Exceptions
NotStrictlyPositiveException:
if p <= 0.
Since
2.1
PoissonDistributionback to summary
public PoissonDistribution(RandomGenerator rng, double p, double epsilon, int maxIterations) throws NotStrictlyPositiveException

Creates a new Poisson distribution with specified mean, convergence criterion and maximum number of iterations.

Parameters
rng:RandomGenerator

Random number generator.

p:double

Poisson mean.

epsilon:double

Convergence criterion for cumulative probabilities.

maxIterations:int

the maximum number of iterations for cumulative probabilities.

Exceptions
NotStrictlyPositiveException:
if p <= 0.
Since
3.1
PoissonDistributionback to summary
public PoissonDistribution(double p, double epsilon) throws NotStrictlyPositiveException

Creates a new Poisson distribution with the specified mean and convergence criterion.

Parameters
p:double

Poisson mean.

epsilon:double

Convergence criterion for cumulative probabilities.

Exceptions
NotStrictlyPositiveException:
if p <= 0.
Since
2.1
PoissonDistributionback to summary
public PoissonDistribution(double p, int maxIterations)

Creates a new Poisson distribution with the specified mean and maximum number of iterations.

Parameters
p:double

Poisson mean.

maxIterations:int

Maximum number of iterations for cumulative probabilities.

Since
2.1

Method Detail

cumulativeProbabilityback to summary
public double cumulativeProbability(int x)

Implements org.apache.commons.math3.distribution.IntegerDistribution.cumulativeProbability.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.cumulativeProbability.

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 (cumulative) distribution function (CDF) for this distribution.

Parameters
x:int

the point at which the CDF is evaluated

Returns:double

the probability that a random variable with this distribution takes a value less than or equal to x

getMeanback to summary
public double getMean()

Get the mean for the distribution.

Returns:double

the mean for the distribution.

getNumericalMeanback to summary
public double getNumericalMean()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalMean.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.getNumericalMean.

Use this method to get the numerical value of the mean of this distribution. For mean parameter p, the mean is p.

Returns:double

the mean or Double.NaN if it is not defined

getNumericalVarianceback to summary
public double getNumericalVariance()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalVariance.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.getNumericalVariance.

Use this method to get the numerical value of the variance of this distribution. For mean parameter p, the variance is p.

Returns:double

the variance (possibly Double.POSITIVE_INFINITY or Double.NaN if it is not defined)

getSupportLowerBoundback to summary
public int getSupportLowerBound()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportLowerBound.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.getSupportLowerBound.

Access the lower bound of the support. This method must return the same value as inverseCumulativeProbability(0). In other words, this method must return

inf {x in Z | P(X <= x) > 0}.

The lower bound of the support is always 0 no matter the mean parameter.
Returns:int

lower bound of the support (always 0)

getSupportUpperBoundback to summary
public int getSupportUpperBound()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportUpperBound.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.getSupportUpperBound.

Access the upper bound of the support. This method must return the same value as inverseCumulativeProbability(1). In other words, this method must return

inf {x in R | P(X <= x) = 1}.

The upper bound of the support is positive infinity, regardless of the parameter values. There is no integer infinity, so this method returns Integer.MAX_VALUE.
Returns:int

upper bound of the support (always Integer.MAX_VALUE for positive infinity)

isSupportConnectedback to summary
public boolean isSupportConnected()

Implements org.apache.commons.math3.distribution.IntegerDistribution.isSupportConnected.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.isSupportConnected.

Use this method to get information about whether the support is connected, i.e. whether all integers between the lower and upper bound of the support are included in the support. The support of this distribution is connected.

Returns:boolean

true

logProbabilityback to summary
public double logProbability(int x)

Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.logProbability.

Doc from org.apache.commons.math3.distribution.AbstractIntegerDistribution.logProbability.

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 probability(int).

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

Parameters
x:int

the point at which the PMF is evaluated

Returns:double

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

Annotations
@Override
nextPoissonback to summary
private long nextPoisson(double meanPoisson)
Parameters
meanPoisson:double

Mean of the Poisson distribution.

Returns:long

the next sample.

normalApproximateProbabilityback to summary
public double normalApproximateProbability(int x)

Calculates the Poisson distribution function using a normal approximation. The N(mean, sqrt(mean)) distribution is used to approximate the Poisson distribution. The computation uses "half-correction" (evaluating the normal distribution function at x + 0.5).

Parameters
x:int

Upper bound, inclusive.

Returns:double

the distribution function value calculated using a normal approximation.

probabilityback to summary
public double probability(int x)

Implements org.apache.commons.math3.distribution.IntegerDistribution.probability.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.probability.

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.

Parameters
x:int

the point at which the PMF is evaluated

Returns:double

the value of the probability mass function at x

sampleback to summary
public int sample()

Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.sample.

Implements org.apache.commons.math3.distribution.IntegerDistribution.sample.

Doc from org.apache.commons.math3.distribution.AbstractIntegerDistribution.sample.

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

Algorithm Description:

  • For small means, uses simulation of a Poisson process using Uniform deviates, as described here. The Poisson process (and hence value returned) is bounded by 1000 * mean.
  • For large means, uses the rejection algorithm described in
    Devroye, Luc. (1981).The Computer Generation of Poisson Random Variables
    Computing vol. 26 pp. 197-207.

Returns:int

a random value.

Annotations
@Override
Since
2.2