fsqrt {VGAM}R Documentation

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.

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.

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.

Note

The default has, if theta is 0 or 1, the link function value is -sqrt(2) and +sqrt(2) respectively. These are finite values, therefore one cannot use this link function for general modelling of probabilities because of numerical problem, e.g., with binomialff, cumulative. See the example below.

Author(s)

Thomas W. Yee

See Also

Links.

Examples

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

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

# This is lucky to converge
earg = list(min=0, max=1, mux=5)
data(hunua)
fit.h = vglm(agaaus ~ bs(altitude),
             fam= binomialff(link="fsqrt", earg=earg),
             data=hunua, trace=TRUE, crit="d")
## Not run: 
plotvgam(fit.h, se=TRUE, lcol="red", scol="red",
     main="Red is Hunua, Blue is Waitakere")
## End(Not run)
predict(fit.h, hunua, type="response")[1:3]

## Not run: 
# The following fails.
data(pneumo)
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)
## End(Not run)

[Package VGAM version 0.7-7 Index]