VGAM (version 1.1-5)

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, size = NULL, wrt.param = NULL, bvalue = NULL,
          inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)

Arguments

theta

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

size, wrt.param

size contains the \(k\) matrix which must be of a conformable dimension as theta. Also, if deriv > 0 then wrt.param is either 1 or 2 (1 for with respect to the first parameter, and 2 for with respect to the second parameter (size)).

bvalue

Details at Links.

inverse, deriv, short, tag

Details at Links.

Value

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

Warning

This function works with negbinomial but care is needed because it is numerically fraught. In particular, the first linear/additive predictor must have negative values, and finding good initial values may be difficult, leading to it crashing at the start. Hence 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 some of that this applies here. Setting trace = TRUE is a good idea, as is trying various values of imethod in negbinomial.

Details

The NBD canonical link is \(\log(\theta/ (\theta + k))\) where \(\theta\) is the NBD mean. The canonical link is used for theoretically relating the NBD 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

Miranda, V. S. and Yee, T. W. (2018). On mean function modelling for several one-parameter discrete distributions. Manuscript in preparation.

Yee, T. W. (2014). Reduced-rank vector generalized linear models with two linear predictors. Computational Statistics and Data Analysis, 71, 889--902.

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

See Also

negbinomial, negbinomial.size.

Examples

# NOT RUN {
nbcanlink("mu", short = FALSE)

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

# }
# NOT RUN {
 mymu <- seq(0.5, 10, length = 101)
kmatrix <- matrix(10, length(mymu), 1)
plot(nbcanlink(mymu, size = kmatrix) ~ mymu, las = 1,
     type = "l", col = "blue", xlab = expression({mu}))
# }
# NOT RUN {
# Estimate the parameters from some simulated data
ndata <- data.frame(x2 = runif(nn <- 100))
ndata <- transform(ndata, eta1 = -1 - 1 * x2,  # eta1 < 0
                          size1 = exp(1),
                          size2 = exp(2))
ndata <- transform(ndata,
            mu1 = nbcanlink(eta1, size = size1, inverse = TRUE),
            mu2 = nbcanlink(eta1, size = size2, inverse = TRUE))
ndata <- transform(ndata, y1 = rnbinom(nn, mu = mu1, size = size1),
                          y2 = rnbinom(nn, mu = mu2, size = size2))
summary(ndata)

nbcfit <- vglm(cbind(y1, y2) ~ x2,
            negbinomial(lmu = "nbcanlink", imethod = 1),  # Try this
#            negbinomial(lmu = "nbcanlink", imethod = 2),  # Try this
            data = ndata, trace = TRUE)
coef(nbcfit, matrix = TRUE)
summary(nbcfit)
# }