Algorithmic constants and parameters for a constrained additive
ordination (CAO), by fitting a reduced-rank vector generalized
additive model (RR-VGAM), are set using this function.
This is the control function for cao.
cao.control(Rank = 1, all.knots = FALSE, criterion = "deviance", Cinit = NULL,
Crow1positive = TRUE, epsilon = 1.0e-05, Etamat.colmax = 10,
GradientFunction = FALSE, iKvector = 0.1, iShape = 0.1,
noRRR = ~ 1, Norrr = NA,
SmallNo = 5.0e-13, Use.Init.Poisson.QO = TRUE,
Bestof = if (length(Cinit)) 1 else 10, maxitl = 10,
imethod = 1, bf.epsilon = 1.0e-7, bf.maxit = 10,
Maxit.optim = 250, optim.maxit = 20, sd.sitescores = 1.0,
sd.Cinit = 0.02, suppress.warnings = TRUE,
trace = TRUE, df1.nl = 2.5, df2.nl = 2.5,
spar1 = 0, spar2 = 0, ...)A list with the components corresponding to its arguments, after some basic error checking.
The numerical rank \(R\) of the model, i.e., the number of latent
variables. Currently only Rank = 1 is implemented.
Logical indicating if all distinct points of the smoothing
variables are to be used as knots. Assigning the value
FALSE means fewer knots are chosen when the number
of distinct points is large, meaning less computational
expense. See vgam.control for details.
Convergence criterion. Currently, only one is supported: the deviance is minimized.
Optional initial C matrix which may speed up convergence.
Logical vector of length Rank (recycled if
necessary): are the elements of the first row of C
positive? For example, if Rank is 4, then specifying
Crow1positive = c(FALSE, TRUE) will force C[1,1]
and C[1,3] to be negative, and C[1,2] and
C[1,4] to be positive.
Positive numeric. Used to test for convergence for GLMs fitted in FORTRAN. Larger values mean a loosening of the convergence criterion.
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.
Logical. Whether optim's argument gr
is used or not, i.e., to compute gradient values. Used only if
FastAlgorithm is TRUE. Currently, this argument
must be set to FALSE.
See qrrvglm.control.
Formula giving terms that are not to be included in the
reduced-rank regression (or formation of the latent variables).
The default is to omit the intercept term from the latent
variables. Currently, only noRRR = ~ 1 is implemented.
Defunct. Please use noRRR.
Use of Norrr will become an error soon.
Positive numeric between .Machine$double.eps and
0.0001. Used to avoid under- or over-flow in the
IRLS algorithm.
Logical. If TRUE then the function
.Init.Poisson.QO is used to obtain initial values
for the canonical coefficients C. If FALSE
then random numbers are used instead.
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 works only when
the function generates its own initial value for C, i.e.,
when C are not passed in as initial values.
The default is only a convenient minimal number and users are urged
to increase this value.
Positive integer. Maximum number of Newton-Raphson/Fisher-scoring/local-scoring iterations allowed.
See qrrvglm.control.
Positive numeric. Tolerance used by the modified vector backfitting algorithm for testing convergence.
Positive integer. Number of backfitting iterations allowed in the compiled code.
Positive integer.
Number of iterations given to the function optim
at each of the optim.maxit iterations.
Positive integer.
Number of times optim is invoked.
Numeric. Standard deviation of the
initial values of the site scores, which are generated from
a normal distribution.
Used when Use.Init.Poisson.QO is FALSE.
Standard deviation of the initial values for the elements
of C.
These are normally distributed with mean zero.
This argument is used only if Use.Init.Poisson.QO = FALSE.
Logical. Suppress warnings?
Logical indicating if output should be produced for each
iteration. Having the value TRUE is a good idea for large
data sets.
Numeric and non-negative, recycled to length S.
Nonlinear degrees
of freedom for smooths of the first and second latent variables.
A value of 0 means the smooth is linear. Roughly, a value between
1.0 and 2.0 often has the approximate flexibility of a quadratic.
The user should not assign too large a value to this argument, e.g.,
the value 4.0 is probably too high. The argument df1.nl is
ignored if spar1 is assigned a positive value or values. Ditto
for df2.nl.
Numeric and non-negative, recycled to length S.
Smoothing parameters of the
smooths of the first and second latent variables. The larger the value, the
more smooth (less wiggly) the fitted curves. These arguments are an
alternative to specifying df1.nl and df2.nl. A value
0 (the default) for spar1 means that df1.nl is used.
Ditto for spar2.
The values are on a scaled version of the latent variables.
See Green and Silverman (1994) for more information.
Ignored at present.
T. W. Yee
Many of these arguments are identical to qrrvglm.control.
Here, \(R\) is the Rank, \(M\) is the number
of additive predictors, and \(S\) is the number of responses
(species).
Thus \(M=S\) for binomial and Poisson responses, and
\(M=2S\) for the negative binomial and 2-parameter gamma distributions.
Allowing the smooths too much flexibility means the CAO optimization
problem becomes more difficult to solve. This is because the number
of local solutions increases as the nonlinearity of the smooths
increases. In situations of high nonlinearity, many initial values
should be used, so that Bestof should be assigned a larger
value. In general, there should be a reasonable value of df1.nl
somewhere between 0 and about 3 for most data sets.
Yee, T. W. (2006). Constrained additive ordination. Ecology, 87, 203--213.
Green, P. J. and Silverman, B. W. (1994). Nonparametric Regression and Generalized Linear Models: A Roughness Penalty Approach, London: Chapman & Hall.
cao.
if (FALSE) {
hspider[,1:6] <- scale(hspider[,1:6]) # Standardized environmental vars
set.seed(123)
ap1 <- cao(cbind(Pardlugu, Pardmont, Pardnigr, Pardpull, Zoraspin) ~
WaterCon + BareSand + FallTwig +
CoveMoss + CoveHerb + ReflLux,
family = poissonff, data = hspider,
df1.nl = c(Zoraspin = 2.3, 2.1),
Bestof = 10, Crow1positive = FALSE)
sort(deviance(ap1, history = TRUE)) # A history of all the iterations
Coef(ap1)
par(mfrow = c(2, 3)) # All or most of the curves are unimodal; some are
plot(ap1, lcol = "blue") # quite symmetric. Hence a CQO model should be ok
par(mfrow = c(1, 1), las = 1)
index <- 1:ncol(depvar(ap1)) # lvplot is jagged because only 28 sites
lvplot(ap1, lcol = index, pcol = index, y = TRUE)
trplot(ap1, label = TRUE, col = index)
abline(a = 0, b = 1, lty = 2)
persp(ap1, label = TRUE, col = 1:4)
}
Run the code above in your browser using DataLab