benini1Qlink {VGAMextra}

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

Description

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

Usage

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

Arguments

theta

Numeric or character. See below for further details.

p

Numeric. A single value between 0.0 and 1.0. It is the p–quantile to be modeled by this link function.

y0

Same as benini1.

bvalue, inverse, deriv, short, tag

See Links.

Details

This is a link function to model any p–quantile of the 1–parameter Benini distribution. It is called the benini1Qlink transformation defined as

\log y_0 + \sqrt{\frac{ -\log (1 - p) }{s}}

where y_0 > 0 is a scale parameter and s is a positive shape parameter, as in benini1.

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

In particular, arguments inverse and deriv are disregarded if theta is character.

Value

For deriv = 0, the benini1Qlink transformation of theta, when inverse = FALSE. If inverse = TRUE, then the inverse transformation given by -log(1 - p) / (theta - log y0)^2 is returned.

For deriv = 1, this function returns the derivative d eta / d theta, if inverse = FALSE. Else, the reciprocal d theta / d eta as a function of theta.

If deriv = 2, then the second order derivatives in terms of theta are accordingly returned.

Warning

The horizontal straight line \log y0 is a lower asymptote for this link function as \theta increases to \infty. Thus, when inverse = TRUE and deriv = 0 entries at theta becoming \eta must be greater than \log y0. Else, NaN will be returned. See examples 2 and 3 below.

Note

Numerical instability may occur for values theta too close to zero or lower than \log y0. Use argument bvalue to replace them before computing the link.

Author(s)

V. Miranda and Thomas W. Yee.

See Also

benini1, Links.

Examples

  ## E1. benini1Qlink() and its inverse ##
   p <- 0.50; y0 = 1.25         ## Modeling the median
   my.s <- seq(0, 5, by = 0.1)[-1]
    max(my.s - benini1Qlink(benini1Qlink(my.s, p = p, y0 = y0), 
                            p = p, y0 = y0, inverse  =TRUE))    ## Zero

  ## E2. Plot of the benini1Qlink() transformation and its inverse     ##
  ## Note, inverse = TRUE implies that argument 'theta' becomes 'eta'. ##
  ## which must be greater than log(y0). Else, value less than log(y0) ##
  ## are replaced by NaN.                                              ##
  
   #--- THE LINK
   my.b <- seq(0, 5, by = 0.01)[-1]
   plot(benini1Qlink(theta = my.b, p = p, y0 = y0) ~ my.b,
        type = "l", col = "blue", lty = "dotted", lwd = 3,
        xlim = c(-0.1, 6), ylim = c(-0.1, 5), las = 1,
        main = c("Blue is benini1Qlink(), green is the inverse"),
        ylab = "eta = benini1Qlink", xlab = "theta")
   abline(h = 0, v = 0, lwd = 2)
    
   #--- THE INVERSE
   lines(my.b, benini1Qlink(theta = my.b, p = p, y0 = y0, inv = TRUE),
         col = "green", lwd = 2, lty = "dashed")
   #--- Tracing the identity function for double--check
   lines(my.b, my.b)     
   
    
   ## E3. WARNING! The first two values are less than log(y0)  ##
    benini1Qlink(theta = c(0.10, 0.15, 0.25, 0.35) , p = p, y0 = y0, inverse  = TRUE)