VGAM (version 0.8-2)

uqo.control: 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 i

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, TR

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

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

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 initi

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 te

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.

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

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

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.Poisso

...

Ignored at present.

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.

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.

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()