R: Control Function for CQO/CAO Calibration

calibrate.qrrvglm.control {VGAM} | R Documentation

## Control Function for CQO/CAO Calibration

### Description

Algorithmic constants and parameters for running `calibrate.qrrvglm` are set using this function.

### Usage

    calibrate.qrrvglm.control(object, trace = FALSE, method.optim = "BFGS",
        gridSize = ifelse(Rank == 1, 21, 9), varI.latvar = FALSE, ...)

### Arguments

`object` | The fitted CQO/CAO model. The user should ignore this argument.
`trace` | Logical indicating if output should be produced for each iteration. It is a good idea to set this argument to be `TRUE` since the computations are expensive.
`method.optim` | Character. Fed into the `method` argument of `optim`.
`gridSize` | Numeric, recycled to length `Rank`. Controls the resolution of the grid used for initial values. For each latent variable, an equally spaced grid of length `gridSize` is cast from the smallest site score to the largest site score. Then the likelihood function is evaluated on the grid, and the best fit is chosen as the initial value. Thus increasing the value of `gridSize` increases the chance of obtaining the global solution, however, the computing time increases proportionately.
`varI.latvar` | Logical. For CQO objects only, this argument is fed into `Coef.qrrvglm`.
`...` | Avoids an error message for extraneous arguments.

### Details

Most CQO/CAO users will only need to make use of `trace` and `gridSize`. These arguments should be used inside their call to `calibrate.qrrvglm`, not this function directly.

### Value

A list which with the following components.

`trace` | Numeric (even though the input can be logical).
`gridSize` | Positive integer.
`varI.latvar` | Logical.

### Note

Despite the name of this function, CAO models are handled as well.

### References

Yee, T. W. (2020). On constrained and unconstrained quadratic ordination. Manuscript in preparation.

### See Also

`calibrate.qrrvglm`, `Coef.qrrvglm`.

### Examples

    ## Not run:  hspider[, 1:6] <- scale(hspider[, 1:6])  # Needed for I.tol=TRUE
    set.seed(123)
    p1 <- cqo(cbind(Alopacce, Alopcune, Pardlugu, Pardnigr,
                    Pardpull, Trocterr, Zoraspin) ~
              WaterCon + BareSand + FallTwig + CoveMoss + CoveHerb + ReflLux,
              family = poissonff, data = hspider, I.tol = TRUE)
    sort(deviance(p1, history = TRUE))  # A history of all the iterations
    siteNos <- 3:4  # Calibrate these sites
    cp1 <- calibrate(p1, trace = TRUE,
                     new = data.frame(depvar(p1)[siteNos, ]))

    ## End(Not run)
    ## Not run:
    # Graphically compare the actual site scores with their calibrated values
    persp(p1, main = "Site scores: solid=actual, dashed=calibrated",
          label = TRUE, col = "blue", las = 1)
    abline(v = latvar(p1)[siteNos], col = seq(siteNos))  # Actual site scores
    abline(v = cp1, lty = 2, col = seq(siteNos))  # Calibrated values

    ## End(Not run)

[Package VGAM version 1.1-3 Index]