org.apache.commons.math.distribution
Class PoissonDistributionImpl

java.lang.Object
  org.apache.commons.math.distribution.AbstractDistribution
      org.apache.commons.math.distribution.AbstractIntegerDistribution
          org.apache.commons.math.distribution.PoissonDistributionImpl

All Implemented Interfaces:

Serializable, DiscreteDistribution, Distribution, IntegerDistribution, PoissonDistribution

public class PoissonDistributionImpl
extends AbstractIntegerDistribution
implements PoissonDistribution, Serializable

Implementation for the PoissonDistribution.

Version:

$Revision: 1054524 $ $Date: 2011-01-03 05:59:18 +0100 (lun. 03 janv. 2011) $

See Also:

Serialized Form

Field Summary

static double	DEFAULT_EPSILON Default convergence criterion.
static int	DEFAULT_MAX_ITERATIONS Default maximum number of iterations for cumulative probability calculations.

Fields inherited from class org.apache.commons.math.distribution.AbstractIntegerDistribution

randomData

Constructor Summary

PoissonDistributionImpl(double p)
Create a new Poisson distribution with the given the mean.

PoissonDistributionImpl(double p, double epsilon)
Create a new Poisson distribution with the given mean and convergence criterion.

PoissonDistributionImpl(double p, double epsilon, int maxIterations)
Create a new Poisson distribution with the given mean, convergence criterion and maximum number of iterations.

PoissonDistributionImpl(double p, int maxIterations)
Create a new Poisson distribution with the given mean and maximum number of iterations.

PoissonDistributionImpl(double p, NormalDistribution z)
Deprecated. as of 2.1 (to avoid possibly inconsistent state, the "NormalDistribution" will be instantiated internally)

Method Summary

double	cumulativeProbability(int x) The probability distribution function P(X <= x) for a Poisson distribution.
protected int	getDomainLowerBound(double p) Access the domain value lower bound, based on p, used to bracket a CDF root.
protected int	getDomainUpperBound(double p) Access the domain value upper bound, based on p, used to bracket a CDF root.
double	getMean() Get the Poisson mean for the distribution.
double	getNumericalVariance() Returns the variance of the distribution.
int	getSupportLowerBound() Returns the lower bound of the support for the distribution.
int	getSupportUpperBound() Returns the upper bound of the support for the distribution.
double	normalApproximateProbability(int x) Calculates the Poisson distribution function using a normal approximation.
double	probability(int x) The probability mass function P(X = x) for a Poisson distribution.
int	sample() Generates a random value sampled from this distribution.
void	setMean(double p) Deprecated. as of 2.1 (class will become immutable in 3.0)
void	setNormal(NormalDistribution value) Deprecated. as of 2.1 (class will become immutable in 3.0)

Methods inherited from class org.apache.commons.math.distribution.AbstractIntegerDistribution

cumulativeProbability, cumulativeProbability, cumulativeProbability, inverseCumulativeProbability, isSupportLowerBoundInclusive, isSupportUpperBoundInclusive, probability, reseedRandomGenerator, sample

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.math.distribution.IntegerDistribution

cumulativeProbability, inverseCumulativeProbability

Methods inherited from interface org.apache.commons.math.distribution.DiscreteDistribution

probability

Methods inherited from interface org.apache.commons.math.distribution.Distribution

cumulativeProbability, cumulativeProbability

Field Detail

DEFAULT_MAX_ITERATIONS

public static final int DEFAULT_MAX_ITERATIONS

Default maximum number of iterations for cumulative probability calculations.

Since:

2.1

See Also:

Constant Field Values

DEFAULT_EPSILON

public static final double DEFAULT_EPSILON

Default convergence criterion.

Since:

2.1

See Also:

Constant Field Values

Constructor Detail

PoissonDistributionImpl

public PoissonDistributionImpl(double p)

Create a new Poisson distribution with the given the mean. The mean value must be positive; otherwise an IllegalArgument is thrown.

Parameters:

p - the Poisson mean

Throws:

IllegalArgumentException - if p ≤ 0

PoissonDistributionImpl

public PoissonDistributionImpl(double p,
                               double epsilon,
                               int maxIterations)

Create a new Poisson distribution with the given mean, convergence criterion and maximum number of iterations.

Parameters:

p - the Poisson mean

epsilon - the convergence criteria for cumulative probabilites

maxIterations - the maximum number of iterations for cumulative probabilites

Since:

2.1

PoissonDistributionImpl

public PoissonDistributionImpl(double p,
                               double epsilon)

Create a new Poisson distribution with the given mean and convergence criterion.

Parameters:

p - the Poisson mean

epsilon - the convergence criteria for cumulative probabilites

Since:

2.1

PoissonDistributionImpl

public PoissonDistributionImpl(double p,
                               int maxIterations)

Create a new Poisson distribution with the given mean and maximum number of iterations.

Parameters:

p - the Poisson mean

maxIterations - the maximum number of iterations for cumulative probabilites

Since:

2.1

PoissonDistributionImpl

@Deprecated
public PoissonDistributionImpl(double p,
                                          NormalDistribution z)

Deprecated. as of 2.1 (to avoid possibly inconsistent state, the "NormalDistribution" will be instantiated internally)

Create a new Poisson distribution with the given the mean. The mean value must be positive; otherwise an IllegalArgument is thrown.

Parameters:

p - the Poisson mean

z - a normal distribution used to compute normal approximations.

Throws:

IllegalArgumentException - if p ≤ 0

Since:

1.2

Method Detail

getMean

public double getMean()

Get the Poisson mean for the distribution.

Specified by:

getMean in interface PoissonDistribution

Returns:

the Poisson mean for the distribution.

setMean

@Deprecated
public void setMean(double p)

Deprecated. as of 2.1 (class will become immutable in 3.0)

Set the Poisson mean for the distribution. The mean value must be positive; otherwise an IllegalArgument is thrown.

Specified by:

setMean in interface PoissonDistribution

Parameters:

p - the Poisson mean value

Throws:

IllegalArgumentException - if p ≤ 0

probability

public double probability(int x)

The probability mass function P(X = x) for a Poisson distribution.

Specified by:

probability in interface IntegerDistribution

Parameters:

x - the value at which the probability density function is evaluated.

Returns:

the value of the probability mass function at x

cumulativeProbability

public double cumulativeProbability(int x)
                             throws MathException

The probability distribution function P(X <= x) for a Poisson distribution.

Specified by:

cumulativeProbability in interface IntegerDistribution

Specified by:

cumulativeProbability in class AbstractIntegerDistribution

Parameters:

x - the value at which the PDF is evaluated.

Returns:

Poisson distribution function evaluated at x

Throws:

MathException - if the cumulative probability can not be computed due to convergence or other numerical errors.

normalApproximateProbability

public double normalApproximateProbability(int x)
                                    throws MathException

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

Specified by:

normalApproximateProbability in interface PoissonDistribution

Parameters:

x - the upper bound, inclusive

Returns:

the distribution function value calculated using a normal approximation

Throws:

MathException - if an error occurs computing the normal approximation

sample

public int sample()
           throws MathException

Generates a random value sampled from this distribution.

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.

Overrides:

sample in class AbstractIntegerDistribution

Returns:

random value

Throws:

MathException - if an error occurs generating the random value

Since:

2.2

getDomainLowerBound

protected int getDomainLowerBound(double p)

Access the domain value lower bound, based on p, used to bracket a CDF root. This method is used by AbstractIntegerDistribution.inverseCumulativeProbability(double) to find critical values.

Specified by:

getDomainLowerBound in class AbstractIntegerDistribution

Parameters:

p - the desired probability for the critical value

Returns:

domain lower bound

getDomainUpperBound

protected int getDomainUpperBound(double p)

Access the domain value upper bound, based on p, used to bracket a CDF root. This method is used by AbstractIntegerDistribution.inverseCumulativeProbability(double) to find critical values.

Specified by:

getDomainUpperBound in class AbstractIntegerDistribution

Parameters:

p - the desired probability for the critical value

Returns:

domain upper bound

setNormal

@Deprecated
public void setNormal(NormalDistribution value)

Deprecated. as of 2.1 (class will become immutable in 3.0)

Modify the normal distribution used to compute normal approximations. The caller is responsible for insuring the normal distribution has the proper parameter settings.

Parameters:

value - the new distribution

Since:

1.2

getSupportLowerBound

public int getSupportLowerBound()

Returns the lower bound of the support for the distribution. The lower bound of the support is always 0 no matter the mean parameter.

Returns:

lower bound of the support (always 0)

Since:

2.2

getSupportUpperBound

public int getSupportUpperBound()

Returns the upper bound of the support for the distribution. 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 and AbstractIntegerDistribution.isSupportUpperBoundInclusive() returns true.

Returns:

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

Since:

2.2

getNumericalVariance

public double getNumericalVariance()

Returns the variance of the distribution. For mean parameter p, the variance is p

Returns:

the variance

Since:

2.2