cloglog {VGAM} | R Documentation

## Complementary Log-log Link Function

### Description

Computes the complementary log-log transformation, including its inverse and the first two derivatives.

### Usage

    cloglog(theta, earg = list(), 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`.
`inverse` | Logical. If `TRUE` the inverse function is computed.
`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 complementary log-log link function is 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 arguments `short` and `tag` are used only if `theta` is character.

### Value

For `deriv = 0`, the complimentary log-log of `theta`, i.e., `log(-log(1 - theta))` when `inverse = FALSE`, and if `inverse = TRUE` then `1-exp(-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. One way of overcoming this is to use `earg`.

With constrained ordination (e.g., `cqo` and `cao`) used with `binomialff`, a complementary log-log link function is preferred over the default `logit` link, for a good reason. See the example below.

In terms of the threshold approach with cumulative probabilities for an ordinal response this link function corresponds to the extreme value distribution.

### Author(s)

Thomas W. Yee

### References

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

### See Also

`Links`, `logit`, `probit`, `cauchit`.

### Examples

    p = seq(0.01, 0.99, by=0.01)
    cloglog(p)
    max(abs(cloglog(cloglog(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))
    cloglog(p)  # Has NAs
    cloglog(p, earg=list(bvalue= .Machine$double.eps))  # Has no NAs

    ## Not run:
    plot(p, logit(p), type="l", col="limegreen", ylab="transformation",
         lwd=2, las=1, main="Some probability link functions")
    lines(p, probit(p), col="purple", lwd=2)
    lines(p, cloglog(p), col="chocolate", lwd=2)
    lines(p, cauchit(p), col="tan", lwd=2)
    abline(v=0.5, h=0, lty="dashed")
    legend(0.1, 4, c("logit", "probit", "cloglog", "cauchit"),
           col=c("limegreen","purple","chocolate", "tan"), lwd=2)
    ## End(Not run)

    # This example shows that a cloglog link is preferred over the logit
    n = 500; p = 5; S = 3; Rank = 1  # Species packing model:
    mydata = rcqo(n, p, S, EqualTol=TRUE, ESOpt=TRUE, EqualMax=TRUE,
                  family="binomial", hiabundance=5, seed=123, Rank=Rank)
    fitc = cqo(attr(mydata, "formula"), ITol=TRUE, data=mydata,
               fam=binomialff(mv=TRUE, link="cloglog"), Rank=Rank)
    fitl = cqo(attr(mydata, "formula"), ITol=TRUE, data=mydata,
               fam=binomialff(mv=TRUE, link="logit"), Rank=Rank)

    # Compare the fitted models (cols 1 and 3) with the truth (col 2)
    cbind(ccoef(fitc), attr(mydata, "ccoefficients"), ccoef(fitl))

[Package VGAM version 0.7-9 Index]