VGAM (version 1.1-8)

lvplot.qrrvglm: Latent Variable Plot for QO models

Description

Produces an ordination diagram (latent variable plot) for quadratic ordination (QO) models. For rank-1 models, the x-axis is the first ordination/constrained/canonical axis. For rank-2 models, the x- and y-axis are the first and second ordination axes respectively.

Usage

lvplot.qrrvglm(object, varI.latvar = FALSE, refResponse = NULL,
    add = FALSE, show.plot = TRUE,
    rug = TRUE, y = FALSE, type = c("fitted.values", "predictors"),
    xlab = paste0("Latent Variable", if (Rank == 1) "" else " 1"),
    ylab = if (Rank == 1) switch(type, predictors = "Predictors",
    fitted.values = "Fitted values") else "Latent Variable 2",
    pcex = par()$cex, pcol = par()$col, pch = par()$pch,
    llty = par()$lty, lcol = par()$col, llwd = par()$lwd,
    label.arg = FALSE, adj.arg = -0.1,
    ellipse = 0.95, Absolute = FALSE, elty = par()$lty,
    ecol = par()$col, elwd = par()$lwd, egrid = 200,
    chull.arg = FALSE, clty = 2, ccol = par()$col, clwd = par()$lwd,
    cpch = "   ",
    C = FALSE, OriginC = c("origin", "mean"),
    Clty = par()$lty, Ccol = par()$col, Clwd = par()$lwd,
    Ccex = par()$cex, Cadj.arg = -0.1, stretchC = 1,
    sites = FALSE, spch = NULL, scol = par()$col, scex = par()$cex,
    sfont = par()$font, check.ok = TRUE, jitter.y = FALSE, ...)

Value

Returns a matrix of latent variables (site scores) regardless of whether a plot was produced or not.

Arguments

object

A CQO object.

varI.latvar

Logical that is fed into Coef.qrrvglm.

refResponse

Integer or character that is fed into Coef.qrrvglm.

add

Logical. Add to an existing plot? If FALSE, a new plot is made.

show.plot

Logical. Plot it?

rug

Logical. If TRUE, a rug plot is plotted at the foot of the plot (applies to rank-1 models only). These values are jittered to expose ties.

y

Logical. If TRUE, the responses will be plotted (applies only to rank-1 models and if type = "fitted.values".)

type

Either "fitted.values" or "predictors", specifies whether the y-axis is on the response or eta-scales respectively.

xlab

Caption for the x-axis. See par.

ylab

Caption for the y-axis. See par.

pcex

Character expansion of the points. Here, for rank-1 models, points are the response y data. For rank-2 models, points are the optimums. See the cex argument in par.

pcol

Color of the points. See the col argument in par.

pch

Either an integer specifying a symbol or a single character to be used as the default in plotting points. See par. The pch argument can be of length \(M\), the number of species.

llty

Line type. Rank-1 models only. See the lty argument of par.

lcol

Line color. Rank-1 models only. See the col argument of par.

llwd

Line width. Rank-1 models only. See the lwd argument of par.

label.arg

Logical. Label the optimums and C? (applies only to rank-2 models only).

adj.arg

Justification of text strings for labelling the optimums (applies only to rank-2 models only). See the adj argument of par.

ellipse

Numerical, of length 0 or 1 (applies only to rank-2 models only). If Absolute is TRUE then ellipse should be assigned a value that is used for the elliptical contouring. If Absolute is FALSE then ellipse should be assigned a value between 0 and 1, for example, setting ellipse = 0.9 means an ellipse with contour = 90% of the maximum will be plotted about each optimum. If ellipse is a negative value, then the function checks that the model is an equal-tolerances model and varI.latvar = FALSE, and if so, plots circles with radius -ellipse. For example, setting ellipse = -1 will result in circular contours that have unit radius (in latent variable units). If ellipse is NULL or FALSE then no ellipse is drawn around the optimums.

Absolute

Logical. If TRUE, the contours corresponding to ellipse are on an absolute scale. If FALSE, the contours corresponding to ellipse are on a relative scale.

elty

Line type of the ellipses. See the lty argument of par.

ecol

Line color of the ellipses. See the col argument of par.

elwd

Line width of the ellipses. See the lwd argument of par.

egrid

Numerical. Line resolution of the ellipses. Choosing a larger value will result in smoother ellipses. Useful when ellipses are large.

chull.arg

Logical. Add a convex hull around the site scores?

clty

Line type of the convex hull. See the lty argument of par.

ccol

Line color of the convex hull. See the col argument of par.

clwd

Line width of the convex hull. See the lwd argument of par.

cpch

Character to be plotted at the intersection points of the convex hull. Having white spaces means that site labels are not obscured there. See the pch argument of par.

C

Logical. Add C (represented by arrows emanating from OriginC) to the plot?

OriginC

Character or numeric. Where the arrows representing C emanate from. If character, it must be one of the choices given. By default the first is chosen. The value "origin" means c(0,0). The value "mean" means the sample mean of the latent variables (centroid). Alternatively, the user may specify a numerical vector of length 2.

Clty

Line type of the arrows representing C. See the lty argument of par.

Ccol

Line color of the arrows representing C. See the col argument of par.

Clwd

Line width of the arrows representing C. See the lwd argument of par.

Ccex

Numeric. Character expansion of the labelling of C. See the cex argument of par.

Cadj.arg

Justification of text strings when labelling C. See the adj argument of par.

stretchC

Numerical. Stretching factor for C. Instead of using C, stretchC * C is used.

sites

Logical. Add the site scores (aka latent variable values, nu's) to the plot? (applies only to rank-2 models only).

spch

Plotting character of the site scores. The default value of NULL means the row labels of the data frame are used. They often are the site numbers. See the pch argument of par.

scol

Color of the site scores. See the col argument of par.

scex

Character expansion of the site scores. See the cex argument of par.

sfont

Font used for the site scores. See the font argument of par.

check.ok

Logical. Whether a check is performed to see that noRRR = ~ 1 was used. It doesn't make sense to have a latent variable plot unless this is so.

jitter.y

Logical. If y is plotted, jitter it first? This may be useful for counts and proportions.

...

Arguments passed into the plot function when setting up the entire plot. Useful arguments here include xlim and ylim.

Author

Thomas W. Yee

Warning

Interpretation of a latent variable plot (CQO diagram) is potentially very misleading in terms of distances if (i) the tolerance matrices of the species are unequal and (ii) the contours of these tolerance matrices are not included in the ordination diagram.

Details

This function only works for rank-1 and rank-2 QRR-VGLMs with argument noRRR = ~ 1.

For unequal-tolerances models, the latent variable axes can be rotated so that at least one of the tolerance matrices is diagonal; see Coef.qrrvglm for details.

Arguments beginning with ``p'' correspond to the points e.g., pcex and pcol correspond to the size and color of the points. Such ``p'' arguments should be vectors of length 1, or \(n\), the number of sites. For the rank-2 model, arguments beginning with ``p'' correspond to the optimums.

References

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

See Also

lvplot, perspqrrvglm, Coef.qrrvglm, par, cqo.

Examples

set.seed(123); nn <- 200
cdata <- data.frame(x2 = rnorm(nn),  # Mean 0 (needed when I.tol=TRUE)
                    x3 = rnorm(nn),  # Mean 0 (needed when I.tol=TRUE)
                    x4 = rnorm(nn))  # Mean 0 (needed when I.tol=TRUE)
cdata <- transform(cdata, latvar1 =  x2 + x3 - 2*x4,
                          latvar2 = -x2 + x3 + 0*x4)
# Nb. latvar2 is weakly correlated with latvar1
cdata <- transform(cdata,
           lambda1 = exp(6 - 0.5 * (latvar1-0)^2 - 0.5 * (latvar2-0)^2),
           lambda2 = exp(5 - 0.5 * (latvar1-1)^2 - 0.5 * (latvar2-1)^2),
           lambda3 = exp(5 - 0.5 * (latvar1+2)^2 - 0.5 * (latvar2-0)^2))
cdata <- transform(cdata,
            spp1 = rpois(nn, lambda1),
            spp2 = rpois(nn, lambda2),
            spp3 = rpois(nn, lambda3))
set.seed(111)
if (FALSE) {
p2 <- cqo(cbind(spp1, spp2, spp3) ~ x2 + x3 + x4, poissonff,
          data = cdata, Rank = 2, I.tolerances = TRUE,
          Crow1positive = c(TRUE, FALSE))  # deviance = 505.81
if (deviance(p2) > 506) stop("suboptimal fit obtained")
sort(deviance(p2, history = TRUE))  # A history of the iterations
Coef(p2)
}

if (FALSE) {
lvplot(p2, sites = TRUE, spch = "*", scol = "darkgreen", scex = 1.5,
  chull = TRUE, label = TRUE, Absolute = TRUE, ellipse = 140,
  adj = -0.5, pcol = "blue", pcex = 1.3, las = 1, Ccol = "orange",
  C = TRUE, Cadj = c(-0.3, -0.3, 1), Clwd = 2, Ccex = 1.4,
  main = paste("Contours at Abundance = 140 with",
               "convex hull of the site scores")) }
if (FALSE) {
var(latvar(p2))  # A diagonal matrix, i.e., uncorrelated latent vars
var(latvar(p2, varI.latvar = TRUE))  # Identity matrix
Tol(p2)[, , 1:2]  # Identity matrix
Tol(p2, varI.latvar = TRUE)[, , 1:2]  # A diagonal matrix
}