uqo.control {VGAM} | R Documentation |
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
.
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, ...)
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. |
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.
A list with the components corresponding to its arguments, after some basic error checking.
This function is currently very sensitive to initial values. Setting
Bestof
some reasonably large integer is recommended.
This is a difficult optimization problem, and the current algorithm needs to be improved.
T. W. Yee
Yee, T. W. (2005) On constrained and unconstrained quadratic ordination. Manuscript in preparation.
Yee, T. W. (2006) Constrained additive ordination. Ecology, 87, 203–213.
uqo
.
uqo.control()