Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

Links

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. Some link functions handle values up to 3 or 4.

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): logitlink, probitlink, clogloglink, cauchitlink, foldsqrtlink, logclink, gordlink, pordlink, nbordlink.

For positive parameters (i.e., greater than 0): loglink, negloglink, powerlink.

For parameters greater than 1: logloglink, loglogloglink (greater than e).

For parameters between -1 and 1: fisherzlink, rhobitlink.

For parameters between A and B: extlogitlink, logofflink (B = Inf).

For unrestricted parameters (i.e., any value): identitylink, negidentitylink, reciprocallink, negreciprocallink.

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!

In VGAM 1.0-7 (January 2019) all link function names were made to end in the characters "link", e.g., loglink replaces loge, logitlink replaces logit. For this most of them were renamed. Upward compatability holds for older link function names, however, users should adopt the new names immediately.

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("logitlink", "probitlink", "clogloglink", "cauchitlink", "identitylink"), ...) it is now binomialff(link = "logitlink", ...). 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 = "logofflink", eshape = list(offset = 0.5)) is replaced by gev(lshape = logofflink(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(), d3theta.deta3(), eta2theta(), theta2eta() are modified.

From January 2019 onwards, all link function names ended in "link". See above for details.

Author(s)

T. W. Yee

References

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

See Also

Examples

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

logofflink(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:
logofflink(1:5, earg = list(offset = 1))
powerlink(1:5, earg = list(power = 2))

## End(Not run)

fit1 <- vgam(agaaus ~ altitude,
             binomialff(link = "clogloglink"), hunua)  # best
fit2 <- vgam(agaaus ~ altitude,
             binomialff(link =  clogloglink ), 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 = logofflink(offset = 1.1),
                          lshape2 = logofflink(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, logitlink(p), type = "l", col = "blue")
plot(x, logitlink(x, inverse = TRUE), type = "l", col = "blue")
plot(p, logitlink(p, deriv=1), type="l", col="blue") # 1 / (p*(1-p))
plot(p, logitlink(p, deriv=2), type="l", col="blue") # (2*p-1)/(p*(1-p))^2

## End(Not run)

VGAM

Vector Generalized Linear and Additive Models

v1.1-5
GPL-3
Authors
Thomas Yee [aut, cre], Cleve Moler [ctb] (author of several LINPACK routines)
Initial release
2021-01-13

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.