nbcanlink {VGAM} | R Documentation

## 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 (NB) distribution. 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`.

### 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()`.)

### 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 `eta` / d `theta` 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.

Standard errors may be unreliable.

### Note

While theoretically nice, this function is not recommended in general since its value is always negative (linear predictors ought to be unbounded in general). A `loge` link for argument `lmu` is recommended instead.

Numerical instability may occur when `theta` is close to 0 or 1. Values of `theta` which are less than or equal to 0 can be replaced by `bvalue` before computing the link function value. See `Links`.

### Author(s)

Thomas W. Yee

### References

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

    nbcanlink("mu", short = FALSE)

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

    ## Not run:  mymu <- c(seq(0.5, 10, length = 101))
    kmatrix <- matrix(10, length(mymu), 1)
    plot(nbcanlink(mymu, 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 - 1 * x2,  # eta1 < 0
                              size1 = size1,
                              size2 = size2)
    ndata <- transform(ndata,
                mu1 = nbcanlink(eta1, size = size1, inv = TRUE),
                mu2 = nbcanlink(eta1, 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 = 1, max.chunk.MB = 9),
                negbinomial("nbcanlink", imethod = 2),
                stepsize = 0.25, data = ndata,  # Deliberately slow the convergence rate
                maxit = 100, trace = TRUE)  # Warning: may converge to a local soln
    coef(fit, matrix = TRUE)
    summary(fit)

    ## End(Not run)

[Package VGAM version 1.0-2 Index]