logit {VGAM} | R Documentation

## Logit Link Function

### Description

Computes the logit transformation, including its inverse and the first two derivatives.

### Usage

    logit(theta, earg = list(), inverse = FALSE, deriv = 0,
          short = TRUE, tag = FALSE)
    elogit(theta, earg = list(min=0, max=1), inverse = FALSE, deriv = 0,
          short = TRUE, tag = FALSE)

### Arguments

`theta` | Numeric or character. See below for further details.
`earg` | Optional list. Extra argument for passing in additional information. Values of `theta` which are less than or equal to 0 can be replaced by the `bvalue` component of the list `earg` before computing the link function value. Values of `theta` which are greater than or equal to 1 can be replaced by 1 minus the `bvalue` component of the list `earg` before computing the link function value. The component name `bvalue` stands for ``boundary value''. See `Links` for general information about `earg`. Similarly, for `elogit`, values of `theta` less than or equal to A or greater than or equal to B can be replaced by the `bminvalue` and `bmaxvalue` components of the list `earg`. For `elogit`, `earg` should be a list with components `min` giving A, `max` giving B, and for out of range values, `bminvalue` and `bmaxvalue`. If `earg` is used, these component names should not be abbreviated.
`inverse` | Logical. If `TRUE` the inverse function is computed. The inverse logit function is known as the expit function.
`deriv` | Order of the derivative. Integer with value 0, 1 or 2.
`short` | Used for labelling the `blurb` slot of a `vglmff-class` object.
`tag` | Used for labelling the linear/additive predictor in the `initialize` slot of a `vglmff-class` object. Contains a little more information if `TRUE`.

### Details

The logit link function is very commonly used for parameters that lie in the unit interval. Numerical values of `theta` close to 0 or 1 or out of range result in `Inf`, `-Inf`, `NA` or `NaN`.

The extended logit link function `elogit` should be used more generally for parameters that lie in the interval (A,B), say. The formula is

log((theta-A)/(B-theta))

and the default values for A and B correspond to the ordinary logit function. Numerical values of `theta` close to A or B or out of range result in `Inf`, `-Inf`, `NA` or `NaN`. However these can be replaced by values bminvalue and bmaxvalue first before computing the link function.

The arguments `short` and `tag` are used only if `theta` is character.

### Value

For `logit` with `deriv = 0`, the logit of `theta`, i.e., `log(theta/(1-theta))` when `inverse = FALSE`, and if `inverse = TRUE` then `exp(theta)/(1+exp(theta))`.
For `deriv = 1`, then the function returns d `theta` / d `eta` as a function of `theta` if `inverse = FALSE`, else if `inverse = TRUE` then it returns the reciprocal.
Here, all logarithms are natural logarithms, i.e., to base e.

### Note

Numerical instability may occur when `theta` is close to 1 or 0 (for `logit`), or close to A or B for `elogit`. One way of overcoming this is to use `earg`.

In terms of the threshold approach with cumulative probabilities for an ordinal response this link function corresponds to the univariate logistic distribution (see `logistic`).

### Author(s)

Thomas W. Yee

### References

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

### See Also

`Links`, `probit`, `cloglog`, `cauchit`, `logistic1`, `loge`.

### Examples

    p = seq(0.01, 0.99, by=0.01)
    logit(p)
    max(abs(logit(logit(p), inverse=TRUE) - p)) # Should be 0

    p = c(seq(-0.02, 0.02, by=0.01), seq(0.97, 1.02, by=0.01))
    logit(p)  # Has NAs
    logit(p, earg=list(bvalue= .Machine$double.eps))  # Has no NAs

    p = seq(0.9, 2.2, by=0.1)
    elogit(p, earg=list(min=1, max=2,
                        bminvalue = 1 + .Machine$double.eps,
                        bmaxvalue = 2 - .Machine$double.eps))  # Has no NAs

    ## Not run:
    par(mfrow=c(2,2))
    y = seq(-4, 4, length=100)
    for(d in 0:1) {
        matplot(p, cbind(logit(p, deriv=d), probit(p, deriv=d)),
                type="n", col="purple", ylab="transformation",
                lwd=2, las=1,
                main=if(d==0) "Some probability link functions"
                else "First derivative")
        lines(p, logit(p, deriv=d), col="limegreen", lwd=2)
        lines(p, probit(p, deriv=d), col="purple", lwd=2)
        lines(p, cloglog(p, deriv=d), col="chocolate", lwd=2)
        lines(p, cauchit(p, deriv=d), col="tan", lwd=2)
        if(d==0) {
            abline(v=0.5, h=0, lty="dashed")
            legend(0, 4.5, c("logit", "probit", "cloglog", "cauchit"),
                   col=c("limegreen","purple","chocolate", "tan"), lwd=2)
        } else
            abline(v=0.5, lty="dashed")
    }

    for(d in 0) {
        matplot(y, cbind(logit(y, deriv=d, inverse=TRUE),
                         probit(y, deriv=d, inverse=TRUE)),
                type="n", col="purple", xlab="transformation", ylab="p",
                lwd=2, las=1,
                main=if(d==0) "Some inverse probability link functions"
                else "First derivative")
        lines(y, logit(y, deriv=d, inverse=TRUE), col="limegreen", lwd=2)
        lines(y, probit(y, deriv=d, inverse=TRUE), col="purple", lwd=2)
        lines(y, cloglog(y, deriv=d, inverse=TRUE), col="chocolate", lwd=2)
        lines(y, cauchit(y, deriv=d, inverse=TRUE), col="tan", lwd=2)
        if(d==0) {
            abline(h=0.5, v=0, lty="dashed")
            legend(-4, 1, c("logit", "probit", "cloglog", "cauchit"),
                   col=c("limegreen","purple","chocolate", "tan"), lwd=2)
        }
    }

    p = seq(0.21, 0.59, by=0.01)
    plot(p, elogit(p, earg=list(min=0.2, max=0.6)), lwd=2,
         type="l", col="black", ylab="transformation", xlim=c(0,1),
         las=1, main="elogit(p, earg=list(min=0.2, max=0.6)")
    ## End(Not run)

[Package VGAM version 0.7-9 Index]