polf {VGAM} | R Documentation

## Poisson-Ordinal Link Function

### Description

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

### Usage

    polf(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 component `cutpoint`. The cutpoints should be non-negative integers. If `polf()` 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 Poisson-ordinal link function (POLF) 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 Poisson distribution. If the cutpoint is zero then a complementary log-log link is used.

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 Poisson distribution (see `poissonff`) 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`, `ordpoisson`, `poissonff`, `nbolf`, `golf`, `cumulative`.

### Examples

    earg = list(cutpoint=2)
    polf("p", earg=earg, short=FALSE)
    polf("p", earg=earg, tag=TRUE)

    p = seq(0.01, 0.99, by=0.01)
    y = polf(p, earg=earg)
    y. = polf(p, earg=earg, deriv=1)
    max(abs(polf(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="polf()")
    abline(h=0, v=0.5, col="red", lty="dashed")

    plot(p, y., type="l", col="blue",
         main="(Reciprocal of) first POLF derivative")
    ## End(Not run)

    # Rutherford and Geiger data
    ruge = c(57,203,383,525,532,408,273,139,45,27,10,4,0,1,1)
    y = 0:14
    yy = rep(y, times=ruge)
    length(yy)  # 2608 1/8-minute intervals
    cutpoint = 5
    yy01 = ifelse(yy <= cutpoint, 0, 1)
    earg = list(cutpoint=cutpoint)
    fit = vglm(yy01 ~ 1, binomialff(link="polf", earg=earg))
    coef(fit, matrix=TRUE)
    exp(coef(fit))

    # Another example
    nn = 1000
    x2 = sort(runif(nn))
    x3 = runif(nn)
    mymu = exp( 3 + 1 * x2 - 2 * x3)
    y1 = rpois(nn, lambda=mymu)
    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="polf",
               reverse=TRUE, parallel=TRUE, intercept.apply=TRUE,
               mv=TRUE, earg=list(cutpoint=cutpoints[2:3])),
               trace=TRUE)
    head(fit@y)
    head(fitted(fit))
    head(predict(fit))
    coef(fit)
    coef(fit, matrix=TRUE)
    constraints(fit)
    fit@misc$earg

[Package VGAM version 0.7-9 Index]