cloglog                 package:VGAM                 R Documentation

_C_o_m_p_l_e_m_e_n_t_a_r_y _L_o_g-_l_o_g _L_i_n_k _F_u_n_c_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

   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'.

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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.

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

     Thomas W. Yee

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'Links', 'logit', 'probit', 'cauchit'.

_E_x_a_m_p_l_e_s:

     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))

