g01 Chapter Contents
g01 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_hypergeom_dist (g01blc)

## 1  Purpose

nag_hypergeom_dist (g01blc) returns the lower tail, upper tail and point probabilities associated with a hypergeometric distribution.

## 2  Specification

 #include #include
 void nag_hypergeom_dist (Integer n, Integer l, Integer m, Integer k, double *plek, double *pgtk, double *peqk, NagError *fail)

## 3  Description

Let $X$ denote a random variable having a hypergeometric distribution with parameters $n$, $l$ and $m$ ($n\ge l\ge 0$, $n\ge m\ge 0$). Then
 $ProbX=k= m k n-m l-k n l ,$
where $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(0,l-\left(n-m\right)\right)\le k\le \mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(l,m\right)$, $0\le l\le n$ and $0\le m\le n$.
The hypergeometric distribution may arise if in a population of size $n$ a number $m$ are marked. From this population a sample of size $l$ is drawn and of these $k$ are observed to be marked.
The mean of the distribution $\text{}=\frac{lm}{n}$, and the variance $\text{}=\frac{lm\left(n-l\right)\left(n-m\right)}{{n}^{2}\left(n-1\right)}$.
nag_hypergeom_dist (g01blc) computes for given $n$, $l$, $m$ and $k$ the probabilities:
 $plek=ProbX≤k pgtk=ProbX>k peqk=ProbX=k .$
The method is similar to the method for the Poisson distribution described in Knüsel (1986).

## 4  References

Knüsel L (1986) Computation of the chi-square and Poisson distribution SIAM J. Sci. Statist. Comput. 7 1022–1036

## 5  Arguments

1:     nIntegerInput
On entry: the parameter $n$ of the hypergeometric distribution.
Constraint: ${\mathbf{n}}\ge 0$.
2:     lIntegerInput
On entry: the parameter $l$ of the hypergeometric distribution.
Constraint: $0\le {\mathbf{l}}\le {\mathbf{n}}$.
3:     mIntegerInput
On entry: the parameter $m$ of the hypergeometric distribution.
Constraint: $0\le {\mathbf{m}}\le {\mathbf{n}}$.
4:     kIntegerInput
On entry: the integer $k$ which defines the required probabilities.
Constraint: $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(0,{\mathbf{l}}-\left({\mathbf{n}}-{\mathbf{m}}\right)\right)\le {\mathbf{k}}\le \mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{l}},{\mathbf{m}}\right)$.
5:     plekdouble *Output
On exit: the lower tail probability, $\mathrm{Prob}\left\{X\le k\right\}$.
6:     pgtkdouble *Output
On exit: the upper tail probability, $\mathrm{Prob}\left\{X>k\right\}$.
7:     peqkdouble *Output
On exit: the point probability, $\mathrm{Prob}\left\{X=k\right\}$.
8:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_2_INT_ARG_GT
On entry, ${\mathbf{k}}=〈\mathit{\text{value}}〉$ and ${\mathbf{l}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{k}}\le {\mathbf{l}}$.
On entry, ${\mathbf{k}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{k}}\le {\mathbf{m}}$.
On entry, ${\mathbf{l}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{l}}\le {\mathbf{n}}$.
On entry, ${\mathbf{m}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{m}}\le {\mathbf{n}}$.
NE_4_INT_ARG_CONS
On entry, ${\mathbf{k}}=〈\mathit{\text{value}}〉$, ${\mathbf{l}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$ and ${\mathbf{l}}+{\mathbf{m}}-{\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{k}}\ge {\mathbf{l}}+{\mathbf{m}}-{\mathbf{n}}$.
NE_ARG_TOO_LARGE
On entry, n is too large to be represented exactly as a double precision number.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INT_ARG_LT
On entry, ${\mathbf{k}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{k}}\ge 0$.
On entry, ${\mathbf{l}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{l}}\ge 0$.
On entry, ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{m}}\ge 0$.
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_VARIANCE_TOO_LARGE
On entry, the variance $\text{}=\frac{lm\left(n-l\right)\left(n-m\right)}{{n}^{2}\left(n-1\right)}$ exceeds ${10}^{6}$.

## 7  Accuracy

Results are correct to a relative accuracy of at least ${10}^{-6}$ on machines with a precision of $9$ or more decimal digits, and to a relative accuracy of at least ${10}^{-3}$ on machines of lower precision (provided that the results do not underflow to zero).

The time taken by nag_hypergeom_dist (g01blc) depends on the variance (see Section 3) and on $k$. For given variance, the time is greatest when $k\approx lm/n$ ($=$ the mean), and is then approximately proportional to the square-root of the variance.

## 9  Example

This example reads values of $n$, $l$, $m$ and $k$ from a data file until end-of-file is reached, and prints the corresponding probabilities.

### 9.1  Program Text

Program Text (g01blce.c)

### 9.2  Program Data

Program Data (g01blce.d)

### 9.3  Program Results

Program Results (g01blce.r)