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-7 Index]