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)
    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)
    head(predict(fit.h, hunua, type="response"))

    ## Not run:
    # 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)
    ## End(Not run)

[Package VGAM version 0.7-9 Index]