R: Negative Binomial-Ordinal Link Function

nbolf {VGAM} | R Documentation

## Negative Binomial-Ordinal Link Function

### Description

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

### Usage

    nbolf(theta, cutpoint = NULL, k = NULL,
          inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)

### Arguments

`theta` | Numeric or character. See below for further details.
`cutpoint, k` | Here, `k` is the k parameter associated with the negative binomial distribution; see `negbinomial`. The cutpoints should be non-negative integers. If `nbolf()` is used as the link function in `cumulative` then one should choose `reverse = TRUE, parallel = TRUE`.
`inverse, deriv, short, tag` | Details at `Links`.

### Details

The negative binomial-ordinal link function (NBOLF) 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 negative binomial 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 negative binomial distribution (see `negbinomial`) 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`, `negbinomial`, `polf`, `golf`, `nbolf2`, `cumulative`, `CommonVGAMffArguments`.

### Examples

    ## Not run:
    nbolf("p", cutpoint = 2, k = 1, short = FALSE)
    nbolf("p", cutpoint = 2, k = 1, tag = TRUE)

    p <- seq(0.02, 0.98, by = 0.01)
    y <- nbolf(p,cutpoint = 2, k = 1)
    y. <- nbolf(p,cutpoint = 2, k = 1, deriv = 1)
    max(abs(nbolf(y,cutpoint = 2, k = 1, inv = TRUE) - p))  # Should be 0

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

    # Another example
    nn <- 1000
    x2 <- sort(runif(nn))
    x3 <- runif(nn)
    mymu <- exp( 3 + 1 * x2 - 2 * x3)
    k <- 4
    y1 <- rnbinom(nn, mu = mymu, size = k)
    cutpoints <- c(-Inf, 10, 20, Inf)
    cuty <- Cut(y1, breaks = cutpoints)
    #\ dontrun{ plot(x2, x3, col = cuty, pch = as.character(cuty)) }
    table(cuty) / sum(table(cuty))
    fit <- vglm(cuty ~ x2 + x3, trace = TRUE,
                cumulative(reverse = TRUE, multiple.responses = TRUE,
                           parallel = TRUE,
                           link = nbolf(cutpoint = cutpoints[2:3], k = k)))
    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]