The class type negative_binomial_distribution
represents a negative_binomial
distribution: it is used when there are exactly two mutually
exclusive outcomes of a Bernoulli
trial: these outcomes are labelled "success" and "failure".

For k + r Bernoulli trials each with success fraction p, the negative_binomial
distribution gives the probability of observing k failures and r successes
with success on the last trial. The negative_binomial distribution assumes
that success_fraction p is fixed for all (k + r) trials.

Note

The random variable for the negative binomial distribution is the number
of trials, (the number of successes is a fixed property of the distribution)
whereas for the binomial, the random variable is the number of successes,
for a fixed number of trials.

It has the PDF:

The following graph illustrate how the PDF varies as the success fraction
p changes:

Alternatively, this graph shows how the shape of the PDF varies as the
number of successes changes:

The name negative binomial distribution is reserved by some to the case
where the successes parameter r is an integer. This integer version is
also called the Pascal
distribution.

This implementation uses real numbers for the computation throughout
(because it uses the real-valued incomplete
beta function family of functions). This real-valued version is also
called the Polya Distribution.

The Poisson distribution is a generalization of the Pascal distribution,
where the success parameter r is an integer: to obtain the Pascal distribution
you must ensure that an integer value is provided for r, and take integer
values (floor or ceiling) from functions that return a number of successes.

For large values of r (successes), the negative binomial distribution
converges to the Poisson distribution.

The geometric distribution is a special case where the successes parameter
r = 1, so only a first and only success is required. geometric(p) = negative_binomial(1,
p).

The Poisson distribution is a special case for large successes

poisson(λ) = lim r → ∞ negative_binomial(r, r / (λ + r)))

Caution

The Negative Binomial distribution is a discrete distribution: internally,
functions like the cdf
and pdf are treated
"as if" they are continuous functions, but in reality the
results returned from these functions only have meaning if an integer
value is provided for the random variate argument.

The quantile function will by default return an integer result that
has been rounded outwards. That is to say lower
quantiles (where the probability is less than 0.5) are rounded downward,
and upper quantiles (where the probability is greater than 0.5) are
rounded upwards. This behaviour ensures that if an X% quantile is requested,
then at least the requested coverage will be present
in the central region, and no more than the requested
coverage will be present in the tails.

This behaviour can be changed so that the quantile functions are rounded
differently, or even return a real-valued result using Policies.
It is strongly recommended that you read the tutorial Understanding
Quantiles of Discrete Distributions before using the quantile
function on the Negative Binomial distribution. The reference
docs describe how to change the rounding policy for these distributions.

The largest acceptable probability that the true value of the success
fraction is less than the value
returned.

For example, if you observe k failures and r
successes from n = k + r trials the best estimate
for the success fraction is simply r/n, but if you
want to be 95% sure that the true value is greater
than some value, pmin, then:

This function uses the Clopper-Pearson method of computing the lower
bound on the success fraction, whilst many texts refer to this method
as giving an "exact" result in practice it produces an interval
that guarantees at least the coverage required,
and may produce pessimistic estimates for some combinations of failures
and successes. See:

This function uses the Clopper-Pearson method of computing the lower
bound on the success fraction, whilst many texts refer to this method
as giving an "exact" result in practice it produces an interval
that guarantees at least the coverage required,
and may produce pessimistic estimates for some combinations of failures
and successes. See:

This function uses numeric inversion of the negative binomial distribution
to obtain the result: another interpretation of the result, is that it
finds the number of trials (success+failures) that will lead to an alpha
probability of observing k failures or fewer.

Returns the largest number of trials we can conduct and still be 95%
sure of seeing no failures that occur with frequency one in one million.

This function uses numeric inversion of the negative binomial distribution
to obtain the result: another interpretation of the result, is that it
finds the number of trials (success+failures) that will lead to an alpha
probability of observing more than k failures.

The greatest number of failures
k expected to be observed from k+r trials with success fraction
p, at probability P. Note that the value returned is a real-number,
and not an integer. Depending on the use case you may want
to take either the floor or ceiling of the real result. For
example:

The smallest number of failures
k expected to be observed from k+r trials with success fraction
p, at probability P. Note that the value returned is a real-number,
and not an integer. Depending on the use case you may want
to take either the floor or ceiling of the real result. For
example:

(p/(r + k)) * ibeta_derivative(r, static_cast<RealType>(k+1),
p) The function ibeta_derivative
is used here, since it has already been optimised for the lowest
possible error - indeed this is really just a thin wrapper
around part of the internals of the incomplete beta function.

cdf

Using the relation:

cdf = Ip(r, k+1) = ibeta(r, k+1, p)

= ibeta(r, static_cast<RealType>(k+1), p)

cdf complement

Using the relation:

1 - cdf = Ip(k+1, r)

= ibetac(r, static_cast<RealType>(k+1), p)

quantile

ibeta_invb(r, p, P) - 1

quantile from the complement

ibetac_invb(r, p, Q) -1)

mean

r(1-p)/p

variance

r(1-p)/p*p

mode

floor((r-1)*(1-p)/p)

skewness

(2-p)/sqrt(r*(1-p))

kurtosis

6/r+(p*p)/r*(1-p)

kurtosis excess

6/r+(p*p)/r*(1-p)-3

parameter estimation member functions

find_lower_bound_on_p

ibeta_inv(successes, failures + 1, alpha)

find_upper_bound_on_p

ibetac_inv(successes, failures, alpha) plus see comments in
code.

find_minimum_number_of_trials

ibeta_inva(k + 1, p, alpha)

find_maximum_number_of_trials

ibetac_inva(k + 1, p, alpha)

Implementation notes:

The real concept type (that deliberately lacks the Lanczos approximation),
was found to take several minutes to evaluate some extreme test values,
so the test has been disabled for this type.

Much greater speed, and perhaps greater accuracy, might be achieved
for extreme values by using a normal approximation. This is NOT been
tested or implemented.