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, earg = stop("'earg' must be given"), inverse = FALSE,
      deriv = 0, short = TRUE, tag = FALSE)

Arguments

theta Numeric or character. See below for further details.
earg Extra argument for passing in additional information. This must be list with components cutpoint and 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, intercept.apply=TRUE.
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 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.

The arguments short and tag are used only if theta is character.

See Links for general information about VGAM link functions.

Value

See Yee (2007) 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. (2007) Ordinal ordination with normalizing link functions for count data, (in preparation).

See Also

Links, negbinomial, polf, golf, nbolf2, cumulative.

Examples

earg = list(cutpoint=2, k=1)
nbolf("p", earg=earg, short=FALSE)
nbolf("p", earg=earg, tag=TRUE)

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

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

# 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)
## Not run: 
plot(x2, x3, col=cuty, pch=as.character(cuty))
## End(Not run)
table(cuty) / sum(table(cuty))
fit = vglm(cuty ~ x2 + x3, fam = cumulative(link="nbolf",
           reverse=TRUE, parallel=TRUE, intercept.apply=TRUE,
           mv=TRUE, earg=list(cutpoint=cutpoints[2:3], k=k)),
           trace=TRUE)
fit@y[1:5,]
fitted(fit)[1:5,]
predict(fit)[1:5,]
coef(fit)
coef(fit, matrix=TRUE)
constraints(fit)
fit@misc$earg

[Package VGAM version 0.7-7 Index]