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:

     Almost all 'VGAM' link functions have something similar to the
     argument list as given above. That is, there is a matching 'earg'
     for each 'link' argument. 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.

          Almost all 'VGAM' family functions with a single link
          function have an argument (often called 'earg') which will
          allow parameters to be inputted for that link function. For
          'VGAM' family functions with more than one link function
          there usually will be an 'earg'-type argument for each link.
          For example, if there are two links called 'lshape' and
          'lscale' then  the 'earg'-type arguments for these might be
          called 'eshape' and 'escale', say.

 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(1:5, earg=list(offset=1))  # Same as log(1:5 + 1)
     powl(1:5, earg=list(power=2))     # Same as (1: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

     # No matter what the link, the estimated var-cov matrix is the same
     y = rbeta(n=1000, shape1=exp(0), shape2=exp(1))
     fit1 = vglm(y ~ 1, betaff(link="identity"), trace = TRUE, crit="c")
     fit2 = vglm(y ~ 1, betaff(link=logoff, earg=list(offset=1.1)),
                 trace = TRUE, crit="c")
     vcov(fit1, untran=TRUE)
     vcov(fit1, untran=TRUE)-vcov(fit2, untran=TRUE)  # Should be all 0s
     fit1@misc$earg   # No 'special' parameters
     fit2@misc$earg   # Some 'special' parameters are here

     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)

