golf {VGAM} | R Documentation

## Gamma-Ordinal Link Function

### Description

Computes the gamma-ordinal transformation, including its inverse and the first two derivatives.

### Usage

    golf(theta, lambda = 1, cutpoint = NULL,
         inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)

### Arguments

`theta` | Numeric or character. See below for further details.
`lambda, cutpoint` | The former is the shape parameter in `gamma2`. `cutpoint` is optional; if `NULL` then `cutpoint` is ignored from the GOLF definition. If given, the cutpoints should be non-negative integers. If `golf()` is used as the link function in `cumulative` then, if the cutpoints are known, then one should choose `reverse = TRUE, parallel = FALSE ~ -1`. If the cutpoints are unknown, then choose `reverse = TRUE, parallel = TRUE`.
`inverse, deriv, short, tag` | Details at `Links`.

### Details

The gamma-ordinal link function (GOLF) can be applied to a parameter lying in the unit interval. Its purpose is to link cumulative probabilities associated with an ordinal response coming from an underlying 2-parameter gamma distribution.

See `Links` for general information about VGAM link functions.

### Value

See Yee (2012) for details.

### Warning

Prediction may not work on `vglm` or `vgam` etc. objects if this link function is used.

### Note

Numerical values of `theta` too close to 0 or 1 or out of range result in large positive or negative values, or maybe 0 depending on the arguments. Although measures have been taken to handle cases where `theta` is too close to 1 or 0, numerical instabilities may still arise.

In terms of the threshold approach with cumulative probabilities for an ordinal response this link function corresponds to the gamma distribution (see `gamma2`) that has been recorded as an ordinal response using known cutpoints.

### Author(s)

Thomas W. Yee

### References

Yee, T. W. (2012) Ordinal ordination with normalizing link functions for count data, (in preparation).

### See Also

`Links`, `gamma2`, `polf`, `nbolf`, `cumulative`.

### Examples

    ## Not run:
    golf("p", lambda = 1, short = FALSE)
    golf("p", lambda = 1, tag = TRUE)

    p <- seq(0.02, 0.98, len = 201)
    y <- golf(p, lambda = 1)
    y. <- golf(p, lambda = 1, deriv = 1, inverse = TRUE)
    max(abs(golf(y, lambda = 1, inverse = TRUE) - p))  # Should be 0

    #\ dontrun{par(mfrow = c(2, 1), las = 1)
    #plot(p, y, type = "l", col = "blue", main = "golf()")
    #abline(h = 0, v = 0.5, col = "orange", lty = "dashed")
    #plot(p, y., type = "l", col = "blue",
    #     main = "(Reciprocal of) first GOLF derivative")
    #}

    # Another example
    gdata <- data.frame(x2 = sort(runif(nn <- 1000)))
    gdata <- transform(gdata, x3 = runif(nn))
    gdata <- transform(gdata, mymu = exp( 3 + 1 * x2 - 2 * x3))
    lambda <- 4
    gdata <- transform(gdata,
             y1 = rgamma(nn, shape = lambda, scale = mymu / lambda))
    cutpoints <- c(-Inf, 10, 20, Inf)
    gdata <- transform(gdata, cuty = Cut(y1, breaks = cutpoints))

    #\ dontrun{ par(mfrow = c(1, 1), las = 1)
    #with(gdata, plot(x2, x3, col = cuty, pch = as.character(cuty))) }
    with(gdata, table(cuty) / sum(table(cuty)))
    fit <- vglm(cuty ~ x2 + x3, cumulative(multiple.responses = TRUE,
               reverse = TRUE, parallel = FALSE ~ -1,
               link = golf(cutpoint = cutpoints[2:3], lambda = lambda)),
               data = gdata, trace = TRUE)
    head(depvar(fit))
    head(fitted(fit))
    head(predict(fit))
    coef(fit)
    coef(fit, matrix = TRUE)
    constraints(fit)
    fit@misc

    ## End(Not run)

[Package VGAM version 1.0-3 Index]