fsqrt                  package:VGAM                  R Documentation

_F_o_l_d_e_d _S_q_u_a_r_e _R_o_o_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 folded square root transformation, including its
     inverse and the first two derivatives.

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

     fsqrt(theta, earg = list(min=0, max=1, mux=sqrt(2)),
           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: List with components 'min', 'max' and 'mux'. These are called
          L, U and K below.

 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 folded square root link function can be applied to parameters
     that lie between L and U inclusive. Numerical values of 'theta'
     out of range result in 'NA' or 'NaN'.

     The arguments 'short' and 'tag' are used only if 'theta' is
     character.

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

     For 'fsqrt' with 'deriv = 0': K * (sqrt(theta-L) - sqrt(U-theta))
     or 'mux * (sqrt(theta-min) - sqrt(max-theta))' when 'inverse =
     FALSE', and if 'inverse = TRUE' then some more complicated
     function that returns a 'NA' unless 'theta' is between
     '-mux*sqrt(max-min)' and 'mux*sqrt(max-min)'.

     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.

_N_o_t_e:

     The default has, if 'theta' is 0 or 1, the link function value is
     '-sqrt(2)' and '+sqrt(2)' respectively. These are finite values,
     therefore one cannot use this link function for general modelling
     of probabilities because of numerical problem, e.g., with
     'binomialff', 'cumulative'. See the example below.

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

     Thomas W. Yee

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

     'Links'.

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

     p = seq(0.01, 0.99, by=0.01)
     fsqrt(p)
     max(abs(fsqrt(fsqrt(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))
     fsqrt(p)  # Has NAs

     ## Not run: 
     p = seq(0.01, 0.99, by=0.01)
     par(mfrow=c(2,2))
     y = seq(-4, 4, length=100)
     for(d in 0:1) {
         matplot(p, cbind(logit(p, deriv=d), fsqrt(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, fsqrt(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", "fsqrt"),
                    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),
                          fsqrt(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, fsqrt(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", "fsqrt"),
                    col=c("limegreen","purple","chocolate", "tan"), lwd=2)
         }
     }
     ## End(Not run)

     # This is lucky to converge
     earg = list(min=0, max=1, mux=5)
     data(hunua)
     fit.h = vglm(agaaus ~ bs(altitude),
                  fam= binomialff(link="fsqrt", earg=earg),
                  data=hunua, trace=TRUE, crit="d")
     ## Not run: 
     plotvgam(fit.h, se=TRUE, lcol="red", scol="red",
          main="Red is Hunua, Blue is Waitakere")
     ## End(Not run)
     predict(fit.h, hunua, type="response")[1:3]

     ## Not run: 
     # The following fails.
     data(pneumo)
     pneumo = transform(pneumo, let=log(exposure.time))
     earg = list(min=0, max=1, mux=10)
     fit = vglm(cbind(normal, mild, severe) ~ let,
                cumulative(link="fsqrt", earg=earg, par=TRUE, rev=TRUE),
                data = pneumo, trace=TRUE, maxit=200)
     ## End(Not run)

