toppleQlink: Link functions for the quantiles of several 1-parameter...

In VGAMextra: Additions and Extensions of the 'VGAM' Package

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

Description

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

Usage

  toppleQlink(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	Numeric. A single value between 0 and 1. It is the p–quantile to be modeled by this link function.
bvalue, inverse, deriv, short, tag	See Links.

Details

This link function comforms with requirements of VGAM in order to be compatible within the VGLM/VGAM framework. That is, monotonic, onto, among other features. In this line, the toppleQlink transformation arises as the proper link to model any quantile of the Topp–Leone distribution topple. It is defined as

\frac{1 - \sqrt{1 - p^{1/s}}}{m.max}.

Here, s is a shape parameter lying in (0, 1) as in topple, whereas m.max stands for the maximum in (0, 1) of

1 - \sqrt{1 - p^{1/s}}

as a function of s. Note, p is prespecified (fixed) between 0 and 1.

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

Arguments inverse and deriv will be ignored if theta is character.

Value

For deriv = 0, the toppleQlink transformation of theta, when inverse = FALSE. If inverse = TRUE, then the inverse transformation log(p)/log(1 - (1 - theta * m.max)^2) is returned.

For deriv = 1, this function returns d eta / d theta, 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.

Warning

The expression p^{1/s} tends rapidly to zero specially for values of s less than 0.005. Therefore, in such cases numerical values represented as zero may be returned when computing this link function, regardless the value of argument inverse.

Note

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

Author(s)

V. Miranda and Thomas W. Yee.

See Also

topple, Links.

Examples

  ## E1. toppleQLink() and its inverse. ##
  my.s <- ppoints(50); p <- 0.75
  max(my.s - toppleQlink(toppleQlink(my.s, p = p), p = p, inverse  =TRUE))   ## Zero
  toppleQlink(theta = c(-0.15, -0.10, 0.25, 0.35) , p = p, inverse  = FALSE) ## NaNs
  toppleQlink(theta = c(-0.15, -0.10, 0.25, 0.35) , p = p, inverse  = TRUE)  ## NaNs
   
   
  ## E2. toppleQLink() for different avlues of 'p'. ##
  
  plot(toppleQlink(theta = my.s, p = 0.05) ~ my.s,
       type = "l", col = "blue", lty = "dotted", lwd = 3,
       xlim = c(-0.1, 1.65), ylim = c(-0.1, 1.1), las = 1,
       main = c("The toppleQlink() transformation"),
       ylab = "eta = toppleQlink", xlab = "theta")
  abline(h = 0, v = 0, lwd = 2)
  abline(h = 1, v = 1, lty = "dotted", col = "green")
  lines(toppleQlink(theta = my.s, p = 0.25) ~ my.s, lwd = 2, lty = "dashed", col = "gray")
  lines(toppleQlink(theta = my.s, p = 0.50) ~ my.s, lwd = 2, lty = "dashed", col = "brown")
  lines(toppleQlink(theta = my.s, p = 0.75) ~ my.s, lwd = 2, lty = "dashed", col = "orange")
  lines(toppleQlink(theta = my.s, p = 0.95) ~ my.s, lwd = 2, lty = "dashed", col = "gray50")
  legend(1.1, 1.0, c("p = 0.05", "p = 0.25", "p = 0.50", "p = 0.75", "p = 0.95"),
         lwd = rep(2, 5), lty = rep("dashed", 5), 
         col = c("blue", "gray", "brown", "orange", "gray50"))
  

VGAMextra documentation built on Aug. 21, 2025, 5:57 p.m.