bnbinom2: Reparameterised beta-negative binomial distribution

In RTMBdist: Distributions Compatible with Automatic Differentiation by 'RTMB'

Reparameterised beta-negative binomial distribution

Description

Probability mass function, distribution function and random generation for the beta-negative binomial distribution reparameterised in terms of its mean.

Usage

dbnbinom2(x, mu, sigma, nu, log = FALSE)

pbnbinom2(q, mu, sigma, nu, lower.tail = TRUE, log.p = FALSE)

rbnbinom2(n, mu, sigma, nu)

Arguments

x	vector of non-negative counts.
mu	mean parameter, must be positive.
sigma	dispersion parameter, must be positive. The variance is finite only for sigma < 1.
nu	dispersion parameter, must be positive.
log	logical; if TRUE, probabilities are returned on the log scale.
q	vector of quantiles.
lower.tail	logical; if TRUE (default), probabilities are P[X \le q], otherwise P[X > q].
log.p	logical; if TRUE, probabilities are returned on the log scale.
n	number of random values to return (for rbnbinom2).

Details

dbnbinom2 allows for automatic differentiation with RTMB. The parameterisation follows the BNB family of the gamlss.dist package, in which \mu is exactly the mean.

Writing r, a and b for the arguments size, shape1 and shape2 of dbnbinom, the reparameterisation is

a = \frac{1}{\sigma} + 1, \qquad b = \frac{\mu\nu}{\sigma}, \qquad r = \frac{1}{\nu}.

This gives E(X) = \mu for every admissible \sigma and \nu, where the original parameterisation needs a > 1 for a mean to exist at all. The variance is

\mathrm{Var}(X) = \frac{\mu (\sigma + \nu)(\mu\nu + 1)}{\nu (1 - \sigma)},

which is finite for \sigma < 1 and increases without bound as \sigma \to 1. Both \sigma and \nu add dispersion beyond the negative binomial, which is recovered as \sigma \to 0.

Because the mean is pinned to a single parameter, this parameterisation is the more stable of the two to estimate in; see bnbinom for the identifiability problem it avoids.

The distribution function has no closed form and is computed by summing the probability mass function over 0, \ldots, q, so its cost grows with the largest q. It is AD-compatible in the parameters, while q must be numeric data. This is also what one-step-ahead (OSA) residuals via RTMB::oneStepPredict need, so these are supported, e.g. with method = "cdf" and discrete = TRUE.

Value

dbnbinom2 gives the probability mass function, pbnbinom2 gives the distribution function, and rbnbinom2 generates random deviates.

References

Rigby, R. A., Stasinopoulos, D. M., Heller, G. Z., and De Bastiani, F. (2019) Distributions for modeling location, scale, and shape: Using GAMLSS in R, Chapman and Hall/CRC, doi:10.1201/9780429298547. An older version can be found in https://www.gamlss.com/.

See Also

bnbinom, nbinom2, betabinom

Examples

set.seed(123)
x <- rbnbinom2(5, mu = 4, sigma = 0.4, nu = 0.5)
d <- dbnbinom2(x, mu = 4, sigma = 0.4, nu = 0.5)
p <- pbnbinom2(x, mu = 4, sigma = 0.4, nu = 0.5)

RTMBdist documentation built on Oct. 31, 2026, 5:07 p.m.