uqo.control {VGAM} | R Documentation

## Control Function for UQO models

### Description

Algorithmic constants and parameters for an unconstrained quadratic ordination (UQO) model, by fitting a quadratic unconstrained vector generalized additive model (QU-VGLM), are set using this function. It is the control function of `uqo`.

### Usage

    uqo.control(Rank=1, Bestof = if(length(lvstart) &&
                !jitter.sitescores) 1 else 10, CA1 = FALSE, Crow1positive
                = TRUE, epsilon = 1.0e-07, EqualTolerances = ITolerances,
                Etamat.colmax = 10, GradientFunction=TRUE, Hstep = 0.001,
                isdlv = rep(c(2, 1, rep(0.5, len=Rank)), len=Rank),
                ITolerances = FALSE, lvstart = NULL, jitter.sitescores
                = FALSE, maxitl = 40, Maxit.optim = 250, MUXfactor =
                rep(3, length=Rank), optim.maxit = 20, nRmax = 250,
                SD.sitescores = 1.0, SmallNo = 5.0e-13, trace = TRUE,
                Use.Init.Poisson.QO=TRUE, ...)

### Arguments

`Rank` | The numerical rank R of the model, i.e., the number of latent variables or ordination axes. Currently only R=1 is recommended.
`Bestof` | Integer. The best of `Bestof` models fitted is returned. This argument helps guard against local solutions by (hopefully) finding the global solution from many fits. The argument has value 1 if an initial value for the site scores is inputted using `lvstart`.
`CA1` | Logical. If `TRUE` the site scores from a correspondence analysis (CA) are computed and used on the first axis as initial values. Both `CA1` and `Use.Init.Poisson.QO` cannot both be `TRUE`.
`Crow1positive` | Logical vector of length `Rank` (recycled if necessary): are the elements of the first row of the latent variable matrix nu positive? For example, if `Rank` is 2, then specifying `Crow1positive=c(FALSE, TRUE)` will force the first site score's first element to be negative, and the first site score's second element to be positive. Note that there is no C matrix with UQO, but the argument's name comes from `qrrvglm.control` and is left unchanged for convenience.
`epsilon` | Positive numeric. Used to test for convergence for GLMs fitted in FORTRAN. Larger values mean a loosening of the convergence criterion.
`EqualTolerances` | Logical indicating whether each (quadratic) predictor will have equal tolerances. Setting `EqualTolerances=TRUE` can help avoid numerical problems, especially with binary data. Note that the estimated (common) tolerance matrix may or may not be positive-definite. If it is, then it can be scaled to the R x R identity matrix. Setting `ITolerances=TRUE` will fit a common R x R identity matrix as the tolerance matrix to the data, but this is model-driven rather than being data-driven because it forces bell-shaped curves/surfaces onto the data. If the estimated (common) tolerance matrix happens to be positive-definite, then this model is essentially equivalent to the model with `ITolerances=TRUE`. See Details in `cqo` and `qrrvglm.control` for more details.
`Etamat.colmax` | Positive integer, no smaller than `Rank`. Controls the amount of memory used by `.Init.Poisson.QO()`. It is the maximum number of columns allowed for the pseudo-response and its weights. In general, the larger the value, the better the initial value. Used only if `Use.Init.Poisson.QO=TRUE`.
`GradientFunction` | Logical. Whether `optim`'s argument `gr` is used or not, i.e., to compute gradient values. The default value is usually faster on most problems.
`Hstep` | Positive value. Used as the step size in the finite difference approximation to the derivatives by `optim`.
`isdlv` | Initial standard deviations for the latent variables (site scores). Numeric, positive and of length R (recycled if necessary). This argument is used only if `ITolerances=TRUE`. Used by `.Init.Poisson.QO()` to obtain initial values for the constrained coefficients C adjusted to a reasonable value. It adjusts the spread of the site scores relative to a common species tolerance of 1 for each ordination axis. A value between 0.5 and 10 is recommended; a value such as 10 means that the range of the environmental space is very large relative to the niche width of the species. The successive values should decrease because the first ordination axis should have the most spread of site scores, followed by the second ordination axis, etc.
`ITolerances` | Logical. If `TRUE` then the (common) tolerance matrix is the R x R identity matrix by definition. Note that `ITolerances=TRUE` implies `EqualTolerances=TRUE`, but not vice versa. Internally, the quadratic terms will be treated as offsets (in GLM jargon) and so the models can potentially be fitted very efficiently. See Details in `cqo` and `qrrvglm.control` for more details. more details. The success of `ITolerances=TRUE` often depends on suitable values for `isdlv` and/or `MUXfactor`.
`lvstart` | Optional matrix of initial values of the site scores. If given, the matrix must be n by R, where n is the number of sites and R is the rank. This argument overrides the arguments `Use.Init.Poisson.QO` and `CA1`. Good possibilities for `lvstart` are the site scores from a constrained ordination, e.g., from `cqo`.
`jitter.sitescores` | Logical. If `TRUE` the initial values for the site scores are jittered to add a random element to the starting values.
`maxitl` | Positive integer. Number of iterations allowed for the IRLS algorithm implemented in the compiled code.
`Maxit.optim` | Positive integer. Number of iterations given to the function `optim` at each of the `optim.maxit` iterations.
`MUXfactor` | Multiplication factor for detecting large offset values. Numeric, positive and of length R (recycled if necessary). This argument is used only if `ITolerances=TRUE`. Offsets are -0.5 multiplied by the sum of the squares of all R latent variable values. If the latent variable values are too large then this will result in numerical problems. By too large, it is meant that the standard deviation of the latent variable values are greater than `MUXfactor[r] * isdlv[r]` for `r=1:Rank` (this is why centering and scaling all the numerical predictor variables in x_2 is recommended). A value about 3 or 4 is recommended. If failure to converge occurs, try a slightly lower value.
`optim.maxit` | Positive integer. Number of times `optim` is invoked.
`nRmax` | Positive integer. If the number of parameters making up the latent variable values (n multiplied by R) is greater than this argument then a conjugate-gradients algorithm is used, otherwise a quasi-Newton algorithm is used by `optim`. The conjugate-gradients method is more suitable when the number of parameters is large because it requires less memory.
`SD.sitescores` | Numeric. Standard deviation of the initial values of the site scores, which are generated from a normal distribution.
`SmallNo` | Positive numeric between `.Machine$double.eps` and `0.0001`. Used to avoid under- or over-flow in the IRLS algorithm.
`trace` | Logical indicating if output should be produced for each iteration.
`Use.Init.Poisson.QO` | Logical. If `TRUE` then the function `.Init.Poisson.QO()` is used to obtain initial values for the site scores. If `FALSE` then random numbers are used instead. Both `CA1` and `Use.Init.Poisson.QO` cannot both be `TRUE`.
`...` | Ignored at present.

### Details

The algorithm currently used by `uqo` is unsophisticated and fails often. Improvements will hopefully be made soon.

See `cqo` and `qrrvglm.control` for more details that are equally pertinent to UQO.

To reduce the number of parameters being estimated, setting `ITolerances = TRUE` or `EqualTolerances = TRUE` is advised.

### Value

A list with the components corresponding to its arguments, after some basic error checking.

### Warning

This function is currently very sensitive to initial values. Setting `Bestof` some reasonably large integer is recommended.

### Note

This is a difficult optimization problem, and the current algorithm needs to be improved.

### Author(s)

T. W. Yee

### References

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

Yee, T. W. (2006) Constrained additive ordination. Ecology, 87, 203–213.

### See Also

`uqo`.

### Examples

    uqo.control()

[Package VGAM version 0.7-9 Index]