Links                  package:VGAM                  R Documentation

_L_i_n_k _f_u_n_c_t_i_o_n_s _f_o_r _V_G_L_M/_V_G_A_M/_e_t_c. _f_a_m_i_l_i_e_s

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

     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.

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

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

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

     All 'VGAM' link functions have the same argument list as given
     above.  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.

 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.

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

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

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

     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.

_N_o_t_e:

     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.

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

     T. 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:

     'vglm', 'vgam', 'rrvglm'. 'cqo', 'cao', 'uqo'.

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

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

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

     data(hunua)
     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

     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)

