trplot.qrrvglm {VGAM}

Trajectory plot for QRR-VGLMs

Description

Produces a trajectory plot for quadratic reduced-rank vector generalized linear models (QRR-VGLMs). It is only applicable for rank-1 models with argument noRRR = ~ 1.

Usage

trplot.qrrvglm(object, which.species = NULL, add = FALSE,
               show.plot = TRUE,
               label.sites = FALSE, sitenames = rownames(object@y),
               axes.equal = TRUE, cex = par()$cex,
               col = 1:(nos * (nos - 1)/2), log = "",
               lty = rep_len(par()$lty, nos * (nos - 1)/2),
               lwd = rep_len(par()$lwd, nos * (nos - 1)/2),
               tcol = rep_len(par()$col, nos * (nos - 1)/2),
               xlab = NULL, ylab = NULL,
               main = "", type = "b", check.ok = TRUE, ...)

Arguments

object

Object of class "qrrvglm", i.e., a CQO object.

which.species

Integer or character vector specifying the species to be plotted. If integer, these are the columns of the response matrix. If character, these must match exactly with the species' names. The default is to use all species.

add

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

show.plot

Logical. Plot it?

label.sites

Logical. If TRUE, the points on the curves/trajectories are labelled with the sitenames.

sitenames

Character vector. The names of the sites.

axes.equal

Logical. If TRUE, the x- and y-axes will be on the same scale.

cex

Character expansion of the labelling of the site names. Used only if label.sites is TRUE. See the cex argument in par.

col

Color of the lines. See the col argument in par. Here, nos is the number of species.

log

Character, specifying which (if any) of the x- and y-axes are to be on a logarithmic scale. See the log argument in par.

lty

Line type. See the lty argument of par.

lwd

Line width. See the lwd argument of par.

tcol

Color of the text for the site names. See the col argument in par. Used only if label.sites is TRUE.

xlab

Character caption for the x-axis. By default, a suitable caption is found. See the xlab argument in plot or title.

ylab

Character caption for the y-axis. By default, a suitable caption is found. See the xlab argument in plot or title.

main

Character, giving the title of the plot. See the main argument in plot or title.

type

Character, giving the type of plot. A common option is to use type="l" for lines only. See the type argument of plot.

check.ok

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

...

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

Details

A trajectory plot plots the fitted values of a ‘second’ species against a ‘first’ species. The argument which.species must therefore contain at least two species. By default, all of the species that were fitted in object are plotted. With more than a few species the resulting plot will be very congested, and so it is recommended that only a few species be selected for plotting.

In the above, M is the number of species selected for plotting, so there will be M(M-1)/2 curves/trajectories in total.

A trajectory plot will be fitted only if noRRR = ~ 1 because otherwise the trajectory will not be a smooth function of the latent variables.

Value

A list with the following components.

species.names

A matrix of characters giving the ‘first’ and ‘second’ species. The number of different combinations of species is given by the number of rows. This is useful for creating a legend.

sitenames

A character vector of site names, sorted by the latent variable (from low to high).

Note

Plotting the axes on a log scale is often a good idea. The use of xlim and ylim to control the axis limits is also a good idea, so as to limit the extent of the curves at low abundances or probabilities. Setting label.sites = TRUE is a good idea only if the number of sites is small, otherwise there is too much clutter.

Author(s)

Thomas W. Yee

References

Yee, T. W. (2020). On constrained and unconstrained quadratic ordination. Manuscript in preparation.

See Also

cqo, par, title.

Examples

## Not run:  set.seed(111)  # Leads to the global solution
# hspider[,1:6] <- scale(hspider[,1:6])  # Stdze the environ vars
p1 <- cqo(cbind(Alopacce, Alopcune, Alopfabr, Arctlute,
                Arctperi, Auloalbi, Pardlugu, Pardmont,
                Pardnigr, Pardpull, Trocterr, Zoraspin) ~
          WaterCon + BareSand + FallTwig + CoveMoss +
          CoveHerb + ReflLux,
          poissonff, data = hspider, trace = FALSE)

trplot(p1, which.species = 1:3, log = "xy", type = "b", lty = 1,
       main = "Trajectory plot of three hunting spiders species",
       col = c("blue","red","green"), lwd = 2, label = TRUE) -> ii
legend(0.00005, 0.3, lwd = 2, lty = 1,
       col = c("blue", "red", "green"),
       with(ii, paste(species.names[,1], species.names[,2],
                      sep = " and ")))
abline(a = 0, b = 1, lty = "dashed", col = "grey")  # Ref. line

## End(Not run)