fsqrt: Folded Square Root Link Function

Description

Computes the folded square root transformation, including its inverse and the first two derivatives.

Usage

fsqrt(theta, earg = list(min = 0, max = 1, mux = sqrt(2)),
      inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)

Arguments

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.

Value

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.

Details

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.

Examples

Run this code

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

p = seq(0.01, 0.99, by = 0.01)
par(mfrow = c(2, 2), lwd = (mylwd <- 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", las = 1,
          main = if (d == 0) "Some probability link functions"
          else "First derivative")
  lines(p, logit(p, deriv = d), col = "limegreen")
  lines(p, probit(p, deriv = d), col = "purple")
  lines(p, cloglog(p, deriv = d), col = "chocolate")
  lines(p, fsqrt(p, deriv = d), col = "tan")
  if (d == 0) {
    abline(v = 0.5, h = 0, lty = "dashed")
    legend(0, 4.5, c("logit", "probit", "cloglog", "fsqrt"), lwd = 2,
           col = c("limegreen","purple","chocolate", "tan"))
  } 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")
  lines(y, probit(y, deriv = d, inverse = TRUE), col = "purple")
  lines(y, cloglog(y, deriv = d, inverse = TRUE), col = "chocolate")
  lines(y, fsqrt(y, deriv = d, inverse = TRUE), col = "tan")
  if (d == 0) {
    abline(h = 0.5, v = 0, lty = "dashed")
    legend(-4, 1, c("logit", "probit", "cloglog", "fsqrt"), lwd = 2,
           col = c("limegreen","purple","chocolate", "tan"))
  }
}
par(lwd = 1)

# This is lucky to converge
earg = list(min = 0, max = 1, mux = 5)
fit.h = vglm(agaaus ~ bs(altitude),
             fam =  binomialff(link = "fsqrt", earg = earg),
             data = hunua, trace = TRUE)
plotvgam(fit.h, se = TRUE, lcol = "orange", scol = "orange",
         main = "Orange is Hunua, Blue is Waitakere")
head(predict(fit.h, hunua, type = "response"))


# The following fails.
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)