NegBinomial              package:stats              R Documentation

The Negative Binomial Distribution

Description:

     Density, distribution function, quantile function and random
     generation for the negative binomial distribution with parameters
     'size' and 'prob'.

Usage:

     dnbinom(x, size, prob, mu, log = FALSE)
     pnbinom(q, size, prob, mu, lower.tail = TRUE, log.p = FALSE)
     qnbinom(p, size, prob, mu, lower.tail = TRUE, log.p = FALSE)
     rnbinom(n, size, prob, mu)

Arguments:

       x: vector of (non-negative integer) quantiles.

       q: vector of quantiles.

       p: vector of probabilities.

       n: number of observations. If 'length(n) > 1', the length is
          taken to be the number required.

    size: target for number of successful trials, or dispersion
          parameter (the shape parameter of the gamma mixing
          distribution). Must be strictly positive.

    prob: probability of success in each trial. '0 < prob <= 1'.

      mu: alternative parametrization via mean: see 'Details'.

log, log.p: logical; if TRUE, probabilities p are given as log(p).

lower.tail: logical; if TRUE (default), probabilities are P[X <= x],
          otherwise, P[X > x].

Details:

     The negative binomial distribution with 'size' = n and 'prob' = p
     has density

             p(x) = Gamma(x+n)/(Gamma(n) x!) p^n (1-p)^x

     for x = 0, 1, 2, ..., n > 0 and 0 < p <= 1.

     This represents the number of failures which occur in a sequence
     of Bernoulli trials before a target number of successes is
     reached.

     A negative binomial distribution can arise as a mixture of Poisson
     distributions with mean distributed as a Gamma ('pgamma')
     distribution with scale parameter '(1 - prob)/prob' and shape
     parameter 'size'.  (This definition allows non-integer values of
     'size'.) In this model 'prob' = 'scale/(1+scale)', and the mean is
     'size * (1 - prob)/prob'.

     The alternative parametrization (often used in ecology) is by the
     _mean_ 'mu', and 'size', the _dispersion parameter_, where 'prob'
     = 'size/(size+mu)'. The variance is 'mu + mu^2/size' in this
     parametrization or n (1-p)/p^2 in the first one.

     If an element of 'x' is not integer, the result of 'dnbinom' is
     zero, with a warning.

     The quantile is defined as the smallest value x such that F(x) >=
     p, where F is the distribution function.

Value:

     'dnbinom' gives the density, 'pnbinom' gives the distribution
     function, 'qnbinom' gives the quantile function, and 'rnbinom'
     generates random deviates.

     Invalid 'size' or 'prob' will result in return value 'NaN', with a
     warning.

Source:

     'dnbinom' computes via binomial probabilities, using code
     contributed by Catherine Loader (see 'dbinom').

     'pnbinom' uses 'pbeta'.

     'qnbinom' uses the Cornish-Fisher Expansion to include a skewness
     correction to a normal approximation, followed by a search.

     'rnbinom' uses the derivation as a gamma mixture of Poissons, see

     Devroye, L. (1986) _Non-Uniform Random Variate Generation._
     Springer-Verlag, New York. Page 480.

See Also:

     'dbinom' for the binomial, 'dpois' for the Poisson and 'dgeom' for
     the geometric distribution, which is a special case of the
     negative binomial.

Examples:

     require(graphics)
     x <- 0:11
     dnbinom(x, size = 1, prob = 1/2) * 2^(1 + x) # == 1
     126 /  dnbinom(0:8, size  = 2, prob  = 1/2) #- theoretically integer

     ## Cumulative ('p') = Sum of discrete prob.s ('d');  Relative error :
     summary(1 - cumsum(dnbinom(x, size = 2, prob = 1/2)) /
                       pnbinom(x, size  = 2, prob = 1/2))

     x <- 0:15
     size <- (1:20)/4
     persp(x,size, dnb <- outer(x, size, function(x,s) dnbinom(x,s, prob= 0.4)),
           xlab = "x", ylab = "s", zlab="density", theta = 150)
     title(tit <- "negative binomial density(x,s, pr = 0.4)  vs.  x & s")

     image  (x,size, log10(dnb), main= paste("log [",tit,"]"))
     contour(x,size, log10(dnb),add=TRUE)

     ## Alternative parametrization
     x1 <- rnbinom(500, mu = 4, size = 1)
     x2 <- rnbinom(500, mu = 4, size = 10)
     x3 <- rnbinom(500, mu = 4, size = 100)
     h1 <- hist(x1, breaks = 20, plot = FALSE)
     h2 <- hist(x2, breaks = h1$breaks, plot = FALSE)
     h3 <- hist(x3, breaks = h1$breaks, plot = FALSE)
     barplot(rbind(h1$counts, h2$counts, h3$counts),
             beside = TRUE, col = c("red","blue","cyan"),
             names.arg = round(h1$breaks[-length(h1$breaks)]))

