VGAM (version 0.8-7)

nbcanlink: Negative binomial canonical link function

Description

Computes the negative binomial canonical link transformation, including its inverse and the first two derivatives.

Usage

nbcanlink(theta, earg = list(), inverse = FALSE, deriv = 0,
          short = TRUE, tag = FALSE)

Arguments

theta

Numeric or character. Typically the mean of a negative binomial (NB) distribution. See below for further details.

earg

List. Extra argument for passing in additional information. Here, a size component contains the $k$ matrix which must be of a conformable dimension as theta. Also, if deriv > 0 then a wrt.eta com

inverse

Logical. If TRUE the inverse function is computed.

deriv

Order of the derivative. Integer with value 0, 1 or 2.

short

Used for labelling the blurb slot of a vglmff-class object.

tag

Used for labelling the linear/additive predictor in the initialize slot of a vglmff-class object. Contains a little more information if TRUE.

Value

• For deriv = 0, the above equation when inverse = FALSE, and if inverse = TRUE then kmatrix / expm1(-theta). For deriv = 1, then the function returns d theta / d eta as a function of theta if inverse = FALSE, else if inverse = TRUE then it returns the reciprocal.

Warning

This function currently does not work very well with negbinomial! The NB-C model is sensitive to the initial values and may converge to a local solution. Pages 210 and 309 of Hilbe (2011) notes convergence difficulties (of Newton-Raphson type algorithms), and this applies here. This function should work okay with negbinomial.size. Currently trying something like imethod = 3 or imu, stepsize = 0.5, maxit = 100, zero = -2 should help; see the example below.

Details

The negative binomial (NB) canonical link is $\log(\theta/ (\theta + k))$ where $\theta$ is the mean of a NB distribution. The canonical link is used for theoretically relating the NB to GLM class.

This link function was specifically written for negbinomial and negbinomial.size, and should not be used elsewhere (these VGAM family functions have code that specifically handles nbcanlink().)

References

Yee, T. W. (2012) Two-parameter reduced-rank vector generalized linear models. In preparation.

Hilbe, J. M. (2011) Negative Binomial Regression, 2nd Edition. Cambridge: Cambridge University Press.

See Also

negbinomial, negbinomial.size.

Examples

nbcanlink("mu", short = FALSE)

mymu = 1:10 # Test some basic operations:
kmatrix = matrix(runif(length(mymu)), length(mymu), 1)
eta1 = nbcanlink(mymu, earg = list(size = kmatrix))
ans2 = nbcanlink(eta1, earg = list(size = kmatrix), inverse = TRUE)
max(abs(ans2 - mymu)) # Should be 0

mymu = c(seq(0.5, 10, length = 101))
kmatrix = matrix(10, length(mymu), 1)
plot(nbcanlink(mymu, earg = list(size = kmatrix)) ~ mymu, las = 1,
     type = "l", col = "blue", lwd = 1.5, xlab = expression({mu}))

# Estimate the parameters from some simulated data (see Warning section)
set.seed(123)
ndata <- data.frame(x2 = runif(nn <- 1000 ))
size1 = exp(1); size2 = exp(2)
ndata <- transform(ndata, eta1 = -1 - 2 * x2, # eta1 < 0
                          size1 = size1,
                          size2 = size2)
ndata <- transform(ndata,
            mu1 = nbcanlink(eta1, earg = list(size = size1), inv = TRUE),
            mu2 = nbcanlink(eta1, earg = list(size = size2), inv = TRUE))
ndata <- transform(ndata, y1 = rnbinom(nn, mu = mu1, size = size1),
                          y2 = rnbinom(nn, mu = mu2, size = size2))
head(ndata)
summary(ndata)

fit <- vglm(cbind(y1, y2) ~ x2, negbinomial("nbcanlink", imethod = 3),
            stepsize = 0.5, ndata, # Deliberately slow the convergence rate
            maxit = 100, trace = TRUE) # Warning: may converge to a local soln
coef(fit, matrix = TRUE)
summary(fit)