VGAMextra (version 0.0-1)

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

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.

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.

See Also

benini1, Links.

Examples

# NOT RUN {
  ## 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.                                              ##
  
# }
# NOT RUN {
   #--- 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)     
   
# }
# NOT RUN {
    
   ## 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)
    
# }