mir.stat.distribution.poisson

enum PoissonAlgo: int;

Algorithms used to calculate poisson dstribution.

PoissonAlgo.direct can be more time-consuming for large values of the number of events (k) or the rate of occurences (lambda). Additional algorithms are provided to the user to choose the trade-off between running time and accuracy.

See Also:

Poisson Distribution

direct

Direct

gamma

Gamma Incomplete function

approxNormal

Approximates poisson distribution with normal distribution. Generally a better approximation when lambda > 1000.

approxNormalContinuityCorrection

Approximates poisson distribution with normal distribution (including continuity correction). More accurate than PoissonAlgo.approxNormal. Generally a better approximation when lambda > 10.

template poissonPMF(PoissonAlgo poissonAlgo = PoissonAlgo.direct)

template poissonPMF(string poissonAlgo)

Computes the poisson probability mass function (PMF).

Parameters:

poissonAlgo

algorithm for calculating PMF (default: PoissonAlgo.direct)

See Also:

Poisson Distribution

Examples:

import mir.math.common: approxEqual, exp;

assert(3.poissonPMF(6.0).approxEqual(exp(-6.0) * 216 / 6));
// Can compute directly with differences of upper incomplete gamma function
assert(3.poissonPMF!"gamma"(6.0).approxEqual(poissonPMF(3, 6.0)));
// For large values of k or lambda, can approximate with normal distribution
assert(1_000_000.poissonPMF!"approxNormal"(1_000_000.0).approxEqual(poissonPMF!"gamma"(1_000_000, 1_000_000.0), 10e-3));
// Or closer with continuity correction
assert(1_000_000.poissonPMF!"approxNormalContinuityCorrection"(1_000_000.0).approxEqual(poissonPMF!"gamma"(1_000_000, 1_000_000.0), 10e-3));

T poissonPMF(T)(const size_t k, const T lambda)
if (isFloatingPoint!T);

Parameters:

size_t k	value to evaluate PMF (e.g. number of events)
T lambda	expected rate of occurence

pure nothrow @nogc @safe T fp_poissonPMF(T)(const size_t k, const T lambda)
if (is(T == Fp!size, size_t size));

Computes the poisson probability mass function (PMF) directly with extended floating point types (e.g. Fp!128), which provides additional accuracy for large values of lambda or k.

Parameters:

size_t k	value to evaluate PMF (e.g. number of "heads")
T lambda	expected rate of occurence

See Also:

Poisson Distribution

Examples:

import mir.bignum.fp: Fp;
import mir.conv: to;
import mir.math.common: approxEqual, exp;

for (size_t i; i <= 10; i++) {
    assert(i.fp_poissonPMF(Fp!128(5.0)).to!double.approxEqual(poissonPMF(i, 5.0)));
}

template poissonCDF(PoissonAlgo poissonAlgo = PoissonAlgo.direct)

template poissonCDF(string poissonAlgo)

Computes the poisson cumulative distrivution function (CDF).

Parameters:

poissonAlgo

algorithm for calculating CDF (default: PoissonAlgo.direct)

See Also:

Poisson Distribution

Examples:

import mir.math.common: approxEqual;

assert(3.poissonCDF(6.0).approxEqual(poissonPMF(0, 6.0) + poissonPMF(1, 6.0) + poissonPMF(2, 6.0) + poissonPMF(3, 6.0)));
// Can compute directly with upper incomplete gamma function
assert(3.poissonCDF!"gamma"(6.0).approxEqual(poissonCDF(3, 6.0)));
// For large values of k or lambda, can approximate with normal distribution
assert(1_000_000.poissonCDF!"approxNormal"(1_000_000.0).approxEqual(poissonCDF!"gamma"(1_000_000, 1_000_000.0), 10e-3));
// Or closer with continuity correction
assert(1_000_000.poissonCDF!"approxNormalContinuityCorrection"(1_000_000.0).approxEqual(poissonCDF!"gamma"(1_000_000, 1_000_000.0), 10e-3));

T poissonCDF(T)(const size_t k, const T lambda)
if (isFloatingPoint!T);

Parameters:

size_t k	value to evaluate CDF (e.g. number of events)
T lambda	expected rate of occurence

template poissonCCDF(PoissonAlgo poissonAlgo = PoissonAlgo.direct)

template poissonCCDF(string poissonAlgo)

Computes the poisson complementary cumulative distrivution function (CCDF).

Parameters:

poissonAlgo

algorithm for calculating CCDF (default: PoissonAlgo.direct)

See Also:

Poisson Distribution

Examples:

import mir.math.common: approxEqual;

assert(3.poissonCCDF(6.0).approxEqual(1.0 - (poissonPMF(0, 6.0) + poissonPMF(1, 6.0) + poissonPMF(2, 6.0) + poissonPMF(3, 6.0))));
// Can compute directly with upper incomplete gamma function
assert(3.poissonCCDF!"gamma"(6.0).approxEqual(poissonCCDF(3, 6.0)));
// For large values of k or lambda, can approximate with normal distribution
assert(1_000_000.poissonCCDF!"approxNormal"(1_000_000.0).approxEqual(poissonCCDF!"gamma"(1_000_000, 1_000_000.0), 10e-3));
// Or closer with continuity correction
assert(1_000_000.poissonCCDF!"approxNormalContinuityCorrection"(1_000_000.0).approxEqual(poissonCCDF!"gamma"(1_000_000, 1_000_000.0), 10e-3));

T poissonCCDF(T)(const size_t k, const T lambda)
if (isFloatingPoint!T);

Parameters:

size_t k	value to evaluate CCDF (e.g. number of events)
T lambda	expected rate of occurence

template poissonInvCDF(PoissonAlgo poissonAlgo = PoissonAlgo.direct) if (poissonAlgo == PoissonAlgo.direct || poissonAlgo == PoissonAlgo.approxNormal || poissonAlgo == PoissonAlgo.approxNormalContinuityCorrection)

template poissonInvCDF(PoissonAlgo poissonAlgo) if (poissonAlgo == PoissonAlgo.gamma)

template poissonInvCDF(string poissonAlgo)

Computes the poisson inverse cumulative distrivution function (InvCDF).

For algorithms PoissonAlgo.direct, PoissonAlgo.approxNormal, and PoissonAlgo.approxNormalContinuityCorrection, the inverse CDF returns the number of events (k) given the probability (p) and rate of occurence (lambda). For the Poisson.gamma algorithm, the inverse CDF returns the rate of occurence (lambda) given the probability (p) and the number of events (k).

For PoissonAlgo.direct, if the value of lambda is larger than 16, then an initial guess is made based on PoissonAlgo.approxNormalContinuityCorrection.

Parameters:

poissonAlgo

algorithm for calculating InvCDF (default: PoissonAlgo.direct)

See Also:

Poisson Distribution

Examples:

import mir.math.common: approxEqual;

assert(0.15.poissonInvCDF(6.0) == 3);
// Passing `gamma` returns the rate of occurnece
assert(0.151204.poissonInvCDF!"gamma"(3).approxEqual(6));
// For large values of k or lambda, can approximate with normal distribution
assert(0.5.poissonInvCDF!"approxNormal"(1_000_000.0) == 1_000_000);
// Or closer with continuity correction
assert(0.5009974.poissonInvCDF!"approxNormalContinuityCorrection"(1_000_000.0) == 1_000_002);

size_t poissonInvCDF(T)(const T p, const T lambda)
if (isFloatingPoint!T);

Parameters:

T p	value to evaluate InvCDF
T lambda	expected rate of occurence

pure nothrow @nogc @safe T poissonLPMF(T)(const size_t k, const T lambda)
if (isFloatingPoint!T);

Computes the poisson log probability mass function (LPMF).

Parameters:

size_t k	value to evaluate LPMF (e.g. number of "heads")
T lambda	expected rate of occurence

See Also:

Poisson Distribution

Examples:

import mir.math.common: approxEqual, exp;

for (size_t i; i <= 10; i++) {
    assert(i.poissonLPMF(5.0).exp.approxEqual(poissonPMF(i, 5.0)));
}