Boost: Classical hypergeometric distribution

The following functions return pmf, cdf, qtf or boost class of the hypergeometric distribution, with \(k\) successes (random draws for which the object drawn has a specified feature) in \(n \in \{0, 1 ,2, \ldots, N \}\) draws, without replacement, from a finite population of size \(N \in \{0, 1 ,2, \ldots \}`\) that contains exactly \(K \in \{0, 1 ,2, \ldots, N \}\) objects with that feature, wherein each draw is either a success or a failure, and the support interval \((\max(0,n+K-N), \min(K,n))\), and \(0 \le q \le 1\).

See also Wikipedia [1271], MathWorld [897], BoostMath [84], Team [558], Berkopec [36], Johnson et al. [411] page 251, Ehrhardt [309] (3.9.11).

Ctx.hypergeometric_pmf(k, n, K, N)

where Ctx is Math53 or CtxBoost.

Returns \(\text{pmf}(k)\), the value of the probability mass function (Pmf) of the hypergeometric distribution.

\[\text{pmf}_X(k) = \frac{\displaystyle\binom{K}{k} \binom{N-K}{n-k}}{\displaystyle\binom{N}{n}}.\]

The following example shows both forms of the syntax:

>>> from mpfebnet import *
>>> a = 0; b = 1; t = 0.3; x = 0.6;
>>> print ("HypergeoPdf(x, a, b): ", HypergeoPdf(x, a, b))
>>> print ("dist_hypergeometric(a, b).pdf(x): ", dist_hypergeometric(a, b).pdf(x))
6.3563523462564525615615615614561356E+00

Ctx.hypergeometric_cdf(k, n, K, N)

where Ctx is Math53 or CtxBoost.

Returns \(\text{cdf}(x)\), the value of the cumulative distribution function (Cdf) of the hypergeometric distribution:

\[\text{cdf}_X(k) = \sum_{j=\max(0,n+K-N)}^{k} \text{pmf}_X(j).\]

The following example shows both forms of the syntax:

>>> from mpfebnet import *
>>> a = 0; b = 1; t = 0.3; x = 0.6;
>>> print ("HypergeoCdf(x, a, b): ", HypergeoCdf(x, a, b))
>>> print ("dist_hypergeometric(a, b).cdf(x): ", dist_hypergeometric(a, b).cdf(x))
6.3563523462564525615615615614561356E+00

Ctx.hypergeometric_qtf(q, n, K, N)

where Ctx is Math53 or CtxBoost.

Returns \(\text{qtf}(q)\), the value of the quantile function (Qtf) of the hypergeometric distribution:

There is no known closed exact form for \(\text{qtf}(q)\) or \(\text{isf}(q)\).

The following example shows both forms of the syntax:

>>> from mpfebnet import *
>>> a = 0; b = 1; t = 0.3; q = 0.6;
>>> print ("HypergeoQtf(q, a, b): ", HypergeoQtf(q, a, b))
>>> print ("dist_hypergeometric(a, b).qtf(q): ", dist_hypergeometric(a, b).qtf(q))
6.3563523462564525615615615614561356E+00

class ctx.dist_hypergeometric(n, K, N)

where ctx is fpm, mpm, ipm, dec, gmp or apm.

The hypergeometric distribution is a discrete (lattice) probability distribution with \(k\) successes (random draws for which the object drawn has a specified feature) in \(n \in \{0, 1 ,2, \ldots, N \}\) draws, without replacement, from a finite population of size \(N \in \{0, 1 ,2, \ldots \}`\) that contains exactly \(K \in \{0, 1 ,2, \ldots, N \}\) objects with that feature, wherein each draw is either a success or a failure, and the support interval \((\max(0,n+K-N), \min(K,n))\). See also Wikipedia [1271], MathWorld [897], BoostMath [84], R (Statistical System) [558], Berkopec [36], Johnson et al. [411] page 251.

dist_hypergeometric.pmf(x)

Returns \(\text{pmf}_X(x)\), the probability mass function (pmf) of a random variable \(X\), following an hypergeometric distribution:

\[\text{pmf}_X(x) = \binom{K}{k} \binom{N-K}{n-k} \bigg/ \binom{N}{n} .\]

The following recursions are used for the PMF:

\[f(k+1)= \frac{(n_1 - k)(n-k)}{(k+1)(n_2 - n+k+1} f(k)\]

\[f(k-1)= \frac{k(n_2 - n + k)}{(n_1 - k+1)(n-k+1} f(k)\]

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; x = 3;
>>> print ("pmf: ", hypergeometric(mu, sigma).pmf(x))
6.3563523462564525615615615614561356E-20

dist_hypergeometric.cdf(x)

Returns \(\text{cdf}_X(x)\), the cumulative distribution function (cdf) of a random variable \(X\), following an hypergeometric distribution:

\[\text{cdf}_X(k) = \sum_{j=\max(0,n+K-N)}^{k} \text{pmf}_X(j) = 1 - \text{pmf}_X(k+1) \times {}_3F_2(1,k+1-K,k+1-n;k+2,N+k+2-K-n;1),\]

where \({}_3F_2(\cdot)\) is a generalized hypergeometric function (see hyp3f2().)

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; x = 3;
>>> print ("cdf: ", hypergeometric(mu, sigma).pmf(x))
6.3563523462564525615615615614561356E-20

dist_hypergeometric.sf(x)

Returns \(\text{sf}_X(x)\), the survival function (sf) of a random variable \(X\), following an hypergeometric distribution:

\[\text{sf}_X(k) = \sum_{j=k+1}^{\min(K,n)} \text{pmf}_X(j) = \text{pmf}_X(k+1) \times {}_3F_2(1,k+1-K,k+1-n;k+2,N+k+2-K-n;1),\]

where \({}_3F_2(\cdot)\) is a generalized hypergeometric function (see hyp3f2().)

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; x = 3;
>>> print (" sf: ", hypergeometric(mu, sigma).pmf(x))
sf: 6.3563523462564525615615615614561356E-20

dist_hypergeometric.qtf(q)

Returns \(\text{qtf}_X(x)\), the quantile function (qtf) of a random variable \(X\), following an hypergeometric distribution.

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; q = 0.3;
>>> print ("qtf: ", hypergeometric(mu, sigma).qtf(q))
qtf: 6.3563523462564525615615615614561356E+00

dist_hypergeometric.isf(q)

Returns \(\text{isf}_X(q)\), the inverse survival function (isf) of a random variable \(X\), following an hypergeometric distribution:

\[\text{isf}_X(q) = \text{qtf}_X(1-q).\]

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; q = 0.3;
>>> print ("isf: ", hypergeometric(mu, sigma).isf(q))
6.3563523462564525615615615614561356E+00

dist_hypergeometric.g_x(t)

Returns \(G_X(t)\), the probability generating function of a random variable \(X\), following an hypergeometric distribution:

\[G_X(t) = {}_2F_1(-n, -K; N-K-n+1; t) \binom{N-K}{n} \bigg/ \binom{N}{n} .\]

where \({}_2F_1(\cdot)\) is the Gauss hypergeometric function (see hyp2f1().)

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; t = 0.3;
>>> print ("c_x: ", hypergeometric(mu, sigma).c_x(t))
6.3563523462564525615615615614561356E+00

dist_hypergeometric.c_x(t)

Returns \(C_X(t)\), the characteristic function of a random variable \(X\), following an hypergeometric distribution:

\[C_X(t) = {}_2F_1(-n, -K; N-K-n+1; e^{it}) \binom{N-K}{n} \bigg/ \binom{N}{n} .\]

where \({}_2F_1(\cdot)\) is the Gauss hypergeometric function (see hyp2f1().)

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; t = 0.3;
>>> print ("c_x: ", hypergeometric(mu, sigma).c_x(t))
6.3563523462564525615615615614561356E+00

dist_hypergeometric.m_x(t)

Returns \(M_X(t)\), the moment generating function of a random variable \(X\), following an hypergeometric distribution:

\[M_X(t) = {}_2F_1(-n, -K; N-K-n+1; e^t) \binom{N-K}{n} \bigg/ \binom{N}{n}.\]

\[L_X(t) = {}_2F_1(-n, -K; N-K-n+1; e^{-t}) \binom{N-K}{n} \bigg/ \binom{N}{n}.\]

where \({}_2F_1(\cdot)\) is the Gauss hypergeometric function (see hyp2f1().)

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; t = 0.3;
>>> print ("m_x: ", hypergeometric(mu, sigma).c_x(t))
6.3563523462564525615615615614561356E+00

dist_hypergeometric.k_x(t, k=0)

Returns \(K_X(t)\), the cumulant generating function of a random variable \(X\), following an hypergeometric distribution:

\[K_X(t) = \log \left[( {}_2F_1(-n, -K; N-K-n+1; e^t) \binom{N-K}{n} \bigg/ \binom{N}{n} \right].\]

where \({}_2F_1(\cdot)\) is the Gauss hypergeometric function (see hyp2f1().)

\(K_X(t)\), the cumulant generating function, and its \(j^{\text{th}}\) derivatives, \(K_X^{(j)}(t), j = 1 \ldots k\), of a random variable \(X\), following a hypergeometric distribution, are defined as

\[K_X(t) = \log \left(T \cdot {}_2F_1(a, b; c; e^t)\right), \quad \text{where } a=-n, b=-K, c=N-K-n+1, T = \binom{N-K}{n} \bigg/ \binom{N}{n}.\]

\[K_X^{(1)}(t) = \frac{a \cdot b \cdot e^x \cdot G_1(x)}{c \cdot G_0(x)}, \quad \text{where } G_i(x)={}_2F_1(a+i, b+i; c+i; e^t),\]

\[K_X^{(2)}(t) = -\frac{a^2 \cdot b^2 \cdot e^{2x} \cdot (G_1(x))^2}{c^2 \cdot (G_0(x))^2} + \frac{a \cdot b \cdot e^x \cdot G_1(x)}{c \cdot G_0(x)} + \frac{a(a+1) \cdot b(b+1) \cdot e^{2x} \cdot G_2(x)}{c(c+1) \cdot G_0(x)},\]

\[\begin{split}K_X^{(3)}(t) = \frac{2 a^3 \cdot b^3 \cdot e^{3x} \cdot (G_1(x))^3}{c^3 \cdot (G_0(x))^3} - \frac{3 a^2 \cdot b^2 \cdot e^{2x} \cdot (G_1(x))^2}{c^2 \cdot (G_0(x))^2} - \frac{3 a^2(a+1) \cdot b^2(b+1) \cdot e^{3x} \cdot G_2(x)\cdot G_1(x)}{c(c+1) \cdot G_0(x)} \\ + \frac{a \cdot b \cdot e^x \cdot G_1(x)}{c \cdot G_0(x)} + \frac{3 a(a+1) \cdot b(b+1) \cdot e^{2x} \cdot G_2(x)}{c(c+1) \cdot G_0(x)} + \frac{a(a+1)(a+2) \cdot b(b+1)(b+2) \cdot e^{3x} \cdot G_3(x)}{c(c+1)(c+2) \cdot G_0(x)}\end{split}\]

and for \(j \ge 4\) the derivatives are calculated by numerically differentiating \(K_X^{(3)}(t)\). We also have

\[\frac{\mathrm{d}}{\mathrm{d}z} \biggl({}_2F_1(a,b,c;z)\biggr) = \frac{ab}{c} \cdot {}_2F_1(a+1,b+1,c+1;z), \quad \text{and }\]

\[z(1-z) \cdot \frac{\mathrm{d}^2}{\mathrm{d}z^2} \biggl({}_2F_1(a,b,c;z)\biggr) + (c-(a+b+1)z) \cdot \frac{\mathrm{d}}{\mathrm{d}z} \biggl({}_2F_1(a,b,c;z)\biggr) - ab \cdot{}_2F_1(a,b,c;z) = 0.\]

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; t = 0.3; k = 6;
>>> print ("c_x: ", hypergeometric(mu, sigma).k_x(t, k))
6.3563523462564525615615615614561356E+00

dist_hypergeometric.moments(k)

Returns the first \(j\) raw moments, \(\mu_j, j = 1 \ldots k\), of a random variable \(X\), following an hypergeometric distribution (Wikipedia).

\[\mu'^{}_X(r) = \sum_{j=1}^{j_{\text{max}}} S_{r,j} T_j, \quad \text{where } j_{\text{max}} = \text{min}(r, n, M, N),\]

\[S_{r,1} = S_{r,r} = 1, \quad S_{r+1,j} = j S_{r,j} + S_{r,j-1}, \quad \text{and}\]

\[T_1 = nM/N, \quad T_{j+1} = T_j (n-j) (M-j) / (N-j).\]

\[\mu'_{[r]} = \frac{n! K! (K+(N-K)-r)! }{(n-r)! (K-r)! (K+(N-K))!}\]

\[\mu'_{[r]} = \frac{n! K! (N-r)! }{(n-r)! (K-r)! N!}\]

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; k = 6;
>>> print ("saddlepoint: ", hypergeometric(mu, sigma).moments(k))
6.3563523462564525615615615614561356E+00

dist_hypergeometric.cumulants(k)

Returns the first \(j\) cumulants, \(\kappa_j, j = 1 \ldots k\), of a random variable \(X\), following an hypergeometric distribution. The cumulants are calculated from the moments.

>>> from mpfunlab import *
>>> mp.dps = 30
>>> mu = 0; sigma = 1; k = 6;
>>> print ("saddlepoint: ", hypergeometric(mu, sigma).cumulants(k))
6.3563523462564525615615615614561356E+00

Approximations

ctx.hypergeo_ecf(k, n, K, N, results='cdf')

where ctx is ipm, dec, mpm, or gmp.

Calculates the Edgeworth approximation to the pdf, cdf and sf.

ctx.hypergeo_ecf_inv(q, n, K, N, results='qtf')

where ctx is ipm, dec, mpm, or gmp.

Calculates the Cornish-Fisher approximation to the qtf and isf.

ctx.hypergeo_spa(k, n, K, N, results='cdf')

where ctx is ipm, dec, mpm, or gmp.

Calculates the Luggannini-Rice saddlepoint approximation of the pdf, cdf and sf.

ctx.hypergeo_spa_inv(q, n, K, N, results='qtf')

where ctx is ipm, dec, mpm, or gmp.

Calculates the inverse Jensen saddlepoint approximation of the qtf and isf.