VGAM (version 1.1-14)

qrrvglm.control: Control Function for QRR-VGLMs (CQO)

Description

Algorithmic constants and parameters for a constrained quadratic ordination (CQO), by fitting a quadratic reduced-rank vector generalized linear model (QRR-VGLM), are set using this function. It is the control function for cqo.

Usage

qrrvglm.control(Rank = 1, Bestof = if (length(Cinit)) 1 else 10,
    checkwz = TRUE, Cinit = NULL, Crow1positive = TRUE,
    epsilon = 1.0e-06, EqualTolerances = NULL, eq.tolerances = TRUE,
    Etamat.colmax = 10, FastAlgorithm = TRUE, GradientFunction = TRUE,
    Hstep = 0.001, isd.latvar = rep_len(c(2, 1, rep_len(0.5, Rank)),
    Rank), iKvector = 0.1, iShape = 0.1, ITolerances = NULL,
    I.tolerances = FALSE, maxitl = 40, imethod = 1,
    Maxit.optim = 250, MUXfactor = rep_len(7, Rank),
    noRRR = ~ 1, Norrr = NA, optim.maxit = 20,
    Parscale = if (I.tolerances) 0.001 else 1.0,
    sd.Cinit = 0.02, SmallNo = 5.0e-13, trace = TRUE,
    Use.Init.Poisson.QO = TRUE,
    wzepsilon = .Machine$double.eps^0.75, ...)

Value

A list with components matching the input names.

Details

Recall that the central formula for CQO is $$\eta = B_1^T x_1 + A \nu + \sum_{m=1}^M (\nu^T D_m \nu) e_m$$ where \(x_1\) is a vector (usually just a 1 for an intercept), \(x_2\) is a vector of environmental variables, \(\nu=C^T x_2\) is a \(R\)-vector of latent variables, \(e_m\) is a vector of 0s but with a 1 in the \(m\)th position. QRR-VGLMs are an extension of RR-VGLMs and allow for maximum likelihood solutions to constrained quadratic ordination (CQO) models.

Having I.tolerances = TRUE means all the tolerance matrices are the order-\(R\) identity matrix, i.e., it forces bell-shaped curves/surfaces on all species. This results in a more difficult optimization problem (especially for 2-parameter models such as the negative binomial and gamma) because of overflow errors and it appears there are more local solutions. To help avoid the overflow errors, scaling \(C\) by the factor Parscale can help enormously. Even better, scaling \(C\) by specifying isd.latvar is more understandable to humans. If failure to converge occurs, try adjusting Parscale, or better, setting eq.tolerances = TRUE (and hope that the estimated tolerance matrix is positive-definite). To fit an equal-tolerances model, it is firstly best to try setting I.tolerances = TRUE and varying isd.latvar and/or MUXfactor if it fails to converge. If it still fails to converge after many attempts, try setting eq.tolerances = TRUE, however this will usually be a lot slower because it requires a lot more memory.

With a \(R > 1\) model, the latent variables are always uncorrelated, i.e., the variance-covariance matrix of the site scores is a diagonal matrix.

If setting eq.tolerances = TRUE is used and the common estimated tolerance matrix is positive-definite then that model is effectively the same as the I.tolerances = TRUE model (the two are transformations of each other). In general, I.tolerances = TRUE is numerically more unstable and presents a more difficult problem to optimize; the arguments isd.latvar and/or MUXfactor often must be assigned some good value(s) (possibly found by trial and error) in order for convergence to occur. Setting I.tolerances = TRUE forces a bell-shaped curve or surface onto all the species data, therefore this option should be used with deliberation. If unsuitable, the resulting fit may be very misleading. Usually it is a good idea for the user to set eq.tolerances = FALSE to see which species appear to have a bell-shaped curve or surface. Improvements to the fit can often be achieved using transformations, e.g., nitrogen concentration to log nitrogen concentration.

Fitting a CAO model (see cao) first is a good idea for pre-examining the data and checking whether it is appropriate to fit a CQO model.

References

Yee, T. W. (2004). A new technique for maximum-likelihood canonical Gaussian ordination. Ecological Monographs, 74, 685--701.

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

See Also

cqo, rcqo, Coef.qrrvglm, Coef.qrrvglm-class, optim, binomialff, poissonff, negbinomial, gamma2.

Examples

if (FALSE)  # Poisson CQO with equal tolerances
set.seed(111)  # This leads to the global solution
hspider[,1:6] <- scale(hspider[,1:6])  # Good when I.tolerances = TRUE
p1 <- cqo(cbind(Alopacce, Alopcune, Alopfabr,
                Arctlute, Arctperi, Auloalbi,
                Pardlugu, Pardmont, Pardnigr,
                Pardpull, Trocterr, Zoraspin) ~
          WaterCon + BareSand + FallTwig +
          CoveMoss + CoveHerb + ReflLux,
          poissonff, data = hspider, eq.tolerances = TRUE)
sort(deviance(p1, history = TRUE))  # Iteration history

(isd.latvar <- apply(latvar(p1), 2, sd))  # Approx isd.latvar

# Refit the model with better initial values
set.seed(111)  # This leads to the global solution
p1 <- cqo(cbind(Alopacce, Alopcune, Alopfabr,
                Arctlute, Arctperi, Auloalbi,
                Pardlugu, Pardmont, Pardnigr,
                Pardpull, Trocterr, Zoraspin) ~
          WaterCon + BareSand + FallTwig +
          CoveMoss + CoveHerb + ReflLux,
          I.tolerances = TRUE, poissonff, data = hspider,
          isd.latvar = isd.latvar)  # Note this
sort(deviance(p1, history = TRUE))  # Iteration history