R: Link functions for VGLM/VGAM/etc. families

Links {VGAM} | R Documentation

## Link functions for VGLM/VGAM/etc. families

### Description

The VGAM package provides a number of (parameter) link functions which are described in general here. Collectively, they offer the user considerable choice and flexibility for modelling data.

### Usage

    TypicalVGAMlink(theta, someParameter = 0, bvalue = NULL, inverse = FALSE,
                    deriv = 0, short = TRUE, tag = FALSE)

### Arguments

`theta` | Numeric or character. This is usually theta (default) but can sometimes be eta, depending on the other arguments. If `theta` is character then `inverse` and `deriv` are ignored. The name `theta` should always be the name of the first argument.
`someParameter` | Some parameter, e.g., an offset.
`bvalue` | Boundary value, positive if given. If `0 < theta` then values of `theta` which are less than or equal to 0 can be replaced by `bvalue` before computing the link function value. Values of `theta` which are greater than or equal to 1 can be replaced by 1 minus `bvalue` before computing the link function value. The value `bvalue = .Machine$double.eps` is sometimes a reasonable value, or something slightly higher.

`inverse` | Logical. If `TRUE` and `deriv = 0` then the inverse link value theta is returned, hence the argument `theta` is really eta. In all other cases, the argument `theta` is really theta.
`deriv` | Integer. Either 0, 1, or 2, specifying the order of the derivative.
`short, tag` | Logical. These are used for labelling the `blurb` slot of a `vglmff-class` object. These arguments are used only if `theta` is character, and gives the formula for the link in character form. If `tag = TRUE` then the result is preceeded by a little more information.

### Details

Almost all VGAM link functions have something similar to the argument list as given above. In this help file we have eta = g(theta) where g is the link function, theta is the parameter and eta is the linear/additive predictor. The link g must be strictly monotonic and twice-differentiable in its range.

The following is a brief enumeration of all VGAM link functions.

For parameters lying between 0 and 1 (e.g., probabilities): `logit`, `probit`, `cloglog`, `cauchit`, `foldsqrt`, `logc`, `golf`, `polf`, `nbolf`.

For positive parameters (i.e., greater than 0): `loge`, `negloge`, `powerlink`.

For parameters greater than 1: `loglog`.

For parameters between -1 and 1: `fisherz`, `rhobit`.

For parameters between A and B: `extlogit`, `logoff` (B = Inf).

For unrestricted parameters (i.e., any value): `identity`, `negidentity`, `reciprocal`, `negreciprocal`.

### Value

Returns one of: the link function value or its first or second derivative, the inverse link or its first or second derivative, or a character description of the link.

Here are the general details. If `inverse = FALSE` and `deriv = 0` (default) then the ordinary link function eta = g(theta) is returned.

If `inverse = TRUE` and `deriv = 0` then the inverse link function value is returned, hence `theta` is really eta (the only occasion this happens).

If `inverse = FALSE` and `deriv = 1` then it is d eta / d theta as a function of theta. If `inverse = FALSE` and `deriv = 2` then it is d^2 eta / d theta^2 as a function of theta.

If `inverse = TRUE` and `deriv = 1` then it is d theta / d eta as a function of theta. If `inverse = TRUE` and `deriv = 2` then it is d^2 theta / d eta^2 as a function of theta.

It is only when `deriv = 1` that `linkfun(theta, deriv = 1, inverse = TRUE)` and `linkfun(theta, deriv = 1, inverse = FALSE)` are reciprocals of each other. In particular, `linkfun(theta, deriv = 2, inverse = TRUE)` and `linkfun(theta, deriv = 2, inverse = FALSE)` are not reciprocals of each other in general.

### Warning

The output of link functions changed at VGAM `0.9-9` (date was around 2015-07). Formerly, `linkfun(theta, deriv = 1)` is now `linkfun(theta, deriv = 1, inverse = TRUE)`, or equivalently, `1 / linkfun(theta, deriv = 1, inverse = TRUE)`. Also, formerly, `linkfun(theta, deriv = 2)` was `1 / linkfun(theta, deriv = 2, inverse = TRUE)`. This was a bug. Altogether, these are big changes and the user should beware!

One day in the future, all VGAM link functions may be renamed to end in the characters `"link"`.

### Note

VGAM link functions are generally not compatible with other functions outside the package. In particular, they won't work with `glm` or any other package for fitting GAMs.

From October 2006 onwards, all VGAM family functions will only contain one default value for each link argument rather than giving a vector of choices. For example, rather than `binomialff(link = c("logit", "probit", "cloglog", "cauchit", "identitylink"), ...)` it is now `binomialff(link = "logit", ...)`. No checking will be done to see if the user's choice is reasonable. This means that the user can write his/her own VGAM link function and use it within any VGAM family function. Altogether this provides greater flexibility. The downside is that the user must specify the full name of the link function, by either assigning the link argument the full name as a character string, or just the name itself. See the examples below.

From August 2012 onwards, a major change in link functions occurred. Argument `esigma` (and the like such as `earg`) used to be in VGAM prior to version 0.9-0 (released during the 2nd half of 2012). The major change is that arguments such as `offset` that used to be passed in via those arguments can done directly through the link function. For example, `gev(lshape = "logoff", eshape = list(offset = 0.5))` is replaced by `gev(lshape = logoff(offset = 0.5))`. The `@misc` slot no longer has `link` and `earg` components, but two other components replace these. Functions such as `dtheta.deta()`, `d2theta.deta2()`, `eta2theta()`, `theta2eta()` are modified.

### Author(s)

T. W. Yee

### References

McCullagh, P. and Nelder, J. A. (1989) Generalized Linear Models, 2nd ed. London: Chapman & Hall.

### See Also

`TypicalVGAMfamilyFunction`, `linkfun`, `vglm`, `vgam`, `rrvglm`. `cqo`, `cao`.

### Examples

    logit("a")
    logit("a", short = FALSE)
    logit("a", short = FALSE, tag = TRUE)

    logoff(1:5, offset = 1)  # Same as log(1:5 + 1)
    powerlink(1:5, power = 2)  # Same as (1:5)^2

    ## Not run:  # This is old and no longer works:
    logoff(1:5, earg = list(offset = 1))
    powerlink(1:5, earg = list(power = 2))

    ## End(Not run)

    fit1 <- vgam(agaaus ~ altitude, binomialff(link = "cloglog"), hunua)  # best
    fit2 <- vgam(agaaus ~ altitude, binomialff(link =  cloglog ), hunua)  # okay

    ## Not run:
    # This no longer works since "clog" is not a valid VGAM link function:
    fit3 <- vgam(agaaus ~ altitude, binomialff(link = "clog"), hunua)  # not okay

    # No matter what the link, the estimated var-cov matrix is the same
    y <- rbeta(n = 1000, shape1 = exp(0), shape2 = exp(1))
    fit1 <- vglm(y ~ 1, betaR(lshape1 = "identitylink", lshape2 = "identitylink"),
                 trace = TRUE, crit = "coef")
    fit2 <- vglm(y ~ 1, betaR(lshape1 = logoff(offset = 1.1),
                              lshape2 = logoff(offset = 1.1)), trace = TRUE)
    vcov(fit1, untransform = TRUE)
    vcov(fit1, untransform = TRUE) - vcov(fit2, untransform = TRUE)  # Should be all 0s
    \dontrun{ # This is old:
    fit1@misc$earg  # Some 'special' parameters
    fit2@misc$earg  # Some 'special' parameters are here
    }

    par(mfrow = c(2, 2))
    p <- seq(0.05, 0.95, len = 200)  # A rather restricted range
    x <- seq(-4, 4, len = 200)
    plot(p, logit(p), type = "l", col = "blue")
    plot(x, logit(x, inverse = TRUE), type = "l", col = "blue")
    plot(p, logit(p, deriv = 1), type = "l", col = "blue")  # 1 / (p*(1-p))
    plot(p, logit(p, deriv = 2), type = "l", col = "blue")  # (2*p-1)/(p*(1-p))^2

    ## End(Not run)

[Package VGAM version 1.0-3 Index]