gamma1Qlink {VGAMextra}

Link functions for the quantiles of several 1–parameter continuous distributions

Description

Computes the gamma1Qlink transformation, its inverse and the first two derivatives.

Usage

  gamma1Qlink(theta, p = stop("Argument 'p' must be specified."),
               bvalue = NULL, inverse = FALSE,
               deriv = 0, short = TRUE, tag = FALSE)

Arguments

theta

Numeric or character. It is \theta by default although it could be \eta depending upon other arguments. See Links for further details about this.

p

A numeric vector of p–quantiles (numbers between 0 and 1) to be modeled by this link function.

bvalue, inverse, deriv, short, tag

See Links.

Details

This link function has been specifically designed to model any p–quantile of the 1–parameter gamma distribution, gamma1, in the VGLM/VGAM context. It is defined as

\eta = \log {\tt{qgamma}}({\tt{p}}, {\tt{shape =}} s),

where s is a positive shape parameter as in gamma1, whilst {\tt{qgamma()}} is the quantile function qgamma.

The inverse of the gamma1Qlink cannot be expressed in closed form. Instead, the inverse image, s_{\eta}, of \eta is numerically approximated by newtonRaphson.basic.

Numerical values of s or p out of range will result in Inf, -Inf, NA or NaN correspondingly.

Arguments inverse and deriv are dismissed if theta is character.

Value

For deriv = 0, the gamma1Qlink transformation of theta, when inverse = FALSE. If inverse = TRUE, then theta becomes \eta, and therefore, the approximate inverse image of \eta is returned.

For deriv = 1, the partial derivative d eta / d theta is returned, if inverse = FALSE. If inverse = TRUE, then the reciprocal d theta / d eta as a function of theta.

If deriv = 2, then the second order derivatives as a function of theta.

Note

Numerical instability may occur for values theta too large, or too close to 0.0. Use argument bvalue to replace them before computing the link.

Author(s)

V. Miranda and Thomas W. Yee.

See Also

gamma1, qgamma, Links.

Examples

  ## E1. gamma1QLink() and values causing NaNs or out of range  ##
  
  p <- 0.75                            # The third quartile is of interest.
  my.s <- seq(0, 5, by = 0.1)[-1]
  
  max(my.s - gamma1Qlink(gamma1Qlink(my.s, p = p), p = p, inverse  =TRUE)) ## Zero
  
  ## E2. Special values of theta ##
  gamma1Qlink(theta = c(-0.15, -0.10, 0, 1:10) , p = p, inverse  = FALSE)  ## NaNs
  gamma1Qlink(theta = c(-5, -3, 0, 1:10) , p = p, inverse  = TRUE)         ## Out of range
   
   
  ## E3. Plot of gamma1QLink() and its inverse. ##
  
  
    # gamma1Qlink()
    plot(gamma1Qlink(theta = my.s, p = p) ~ my.s,
         type = "l", col = "blue", lty = "dotted", lwd = 3,
         xlim = c(-0.1, 5), ylim = c(-5, 15), las = 1,
         main = c("Blue is gamma1Qlink(), green is the inverse"),
         ylab = "gamma1Qlink transformation", xlab = "theta")
     abline(h = 0, v = 0, lwd = 2)

     # The inverse
     lines(my.s, gamma1Qlink(theta = my.s, p = p, inverse = TRUE),
           col = "green", lwd = 2, lty = "dashed")
           
      # The identity function, for double-checking.
     lines(my.s, my.s, lty = "dotted")