logit                  package:VGAM                  R Documentation

_L_o_g_i_t _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 logit transformation, including its inverse and the
     first two derivatives.

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

     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)

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

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

     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.

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

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

_N_o_t_e:

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

_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', 'probit', 'cloglog', 'cauchit', 'loge'.

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

     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)

