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 flexibility for modelling data.

### Usage

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

### Arguments

Almost all VGAM link functions have something similar to the argument list as given above. That is, there is a matching `earg` for each `link` argument. In the following we have eta=g(theta) where g is the link function, theta is the parameter and eta is the linear/additive predictor.

`theta` | Numeric or character. Actually this can be theta (default) or eta, depending on the other arguments. If `theta` is character then `inverse` and `deriv` are ignored.
`earg` | List. Extra argument allowing for additional information, specific to the link function. For example, for `logoff`, this will contain the offset value. The argument `earg` is always a list with named components. See each specific link function to find the component names for the list. Almost all VGAM family functions with a single link function have an argument (often called `earg`) which will allow parameters to be inputted for that link function. For VGAM family functions with more than one link function there usually will be an `earg`-type argument for each link. For example, if there are two links called `lshape` and `lscale` then the `earg`-type arguments for these might be called `eshape` and `escale`, say.
`inverse` | Logical. If `TRUE` the inverse link value theta is returned, hence the argument `theta` is really eta.
`deriv` | Integer. Either 0, 1, or 2 specifying the order of the derivative.
`short, tag` | Logical. Used for labelling the `blurb` slot of a `vglmff-class` object. Used only if `theta` is character, and gives the formula for the link in character form. If `tag=TRUE` then the result contains a little more information.

### Details

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`, `loglog`, `fsqrt`, `logc`, `golf`, `polf`, `nbolf`.

For positive parameters (i.e., greater than 0): `loge`, `nloge`, `powl`.

For parameters greater than 1: `loglog`.

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

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

For unrestricted parameters (i.e., any value): `identity`, `nidentity`, `reciprocal`, `nreciprocal`.

### 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=FALSE` and `deriv=1` then it is d theta / d eta as a function of theta. If `inverse=FALSE` and `deriv=2` then it is d^2 theta / d eta^2 as a function of theta.
If `inverse=TRUE` and `deriv=0` then the inverse link function is returned, hence `theta` is really eta. If `inverse=TRUE` and `deriv` is positive then the reciprocal of the same link function with `(theta=theta, earg=earg, inverse=TRUE, deriv=deriv)` is returned.

### Note

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", "identity"), ...)` 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.

### Author(s)

T. W. Yee

### References

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

### See Also

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

### Examples

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

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

    fit1 = vgam(agaaus ~ altitude, binomialff(link=cloglog), hunua)    # ok
    fit2 = vgam(agaaus ~ altitude, binomialff(link="cloglog"), hunua)  # ok

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

    # 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, beta.ab(lshape1="identity", lshape2="identity"),
                trace = TRUE, crit="c")
    fit2 = vglm(y ~ 1, beta.ab(lshape1=logoff, eshape1=list(offset=1.1),
                               lshape2=logoff, eshape2=list(offset=1.1)),
                trace = TRUE, crit="c")
    vcov(fit1, untran=TRUE)
    vcov(fit1, untran=TRUE)-vcov(fit2, untran=TRUE)  # Should be all 0s
    fit1@misc$earg   # No 'special' parameters
    fit2@misc$earg   # Some 'special' parameters are here

    par(mfrow=c(2,2))
    p = seq(0.01, 0.99, len=200)
    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") # reciprocal!
    plot(p, logit(p, deriv=2), type="l", col="blue") # reciprocal!
    ## End(Not run)

[Package VGAM version 0.7-9 Index]