timetrack: Timetracks of change in species composition

Description

Project passive (e.g. sediment core) samples into an ordination of a set of training samples.

Usage

timetrack(X, passive, env, method = c("cca", "rda"),
          transform = "none", formula, scaling = 3,
          rank = "full", join = "left", correlation = FALSE,
          hill = FALSE, ...)
# S3 method for timetrack
fitted(object, which = c("passive", "ordination"),
       model = NULL, choices = 1:2, ...)
# S3 method for timetrack
predict(object, newdata, ...)
# S3 method for timetrack
scores(x, which = c("ordination", "passive"),
       scaling = x$scaling, choices = 1:2, display = "sites", ...)
# S3 method for timetrack
plot(x, choices = 1:2, display = c("wa", "lc"),
     order, type = c("p", "n"), ptype = c("l", "p", "o", "b", "n"),
     pch = c(1,2), col = c("black","red"), lty = "solid", lwd = 1,
     xlim = NULL, ylim = NULL, ...)
# S3 method for timetrack
points(x, choices = 1:2, which = c("passive", "ordination"),
       display = c("wa","lc"), order, ...)

Value

The plot method results in a plot on the currently active device, whilst the fitted and scores methods return the matrix of fitted locations on the set of ordination axes.

timetrack returns an object of class "timetrack", a list with the following components:

ordination: the ordination object, the result of the call to the function of the name method.
fitted.values: the matrix of fitted locations for the passive samples on the ordination axes.
method: the ordination function used.
formula: if supplied, the model formula used to define the ordination model.
scaling: the ordination scaling applied.
rank: The rank or the number of axes used in the approximation. The default is to use all axes (full rank) of the "model".
model: Show constrained ("CCA") or unconstrained ("CA") results.
labels: a list of names for the X, passive, and env arguments.
call: The matched function call.
X: The training data.
transform: The transformation applied, if any.

Arguments

X: matrix-like object containing the training set or reference samples.
passive: matrix-like object containing the samples to be projected into the ordination of X. Usually a set of sediment core samples.
env: optional data frame of environmental or constraining variables. If provided, a constrained ordination of X is performed. If formula is supplied variables named in formula are looked up with env.
method: character, resolving to an ordination function available in vegan. Currently only "cca", the default, and "rda" are supported.
transform: character; the name of the transformation to apply to both X and passive. The transformations are performed using tran and valid options are given by that function's method argument.
formula: a one-sided model formula; if provided, it defines the right hand side of the model formula for the ordination function and is supplied as argument formula to the ordination function. E.g.~formula = ~ var1 + var2. If supplied then env must also be supplied
scaling: numeric or character; the ordination scaling to apply. Useful options are likely to be 1 or 3 where the focus is on the samples. For character, see options in scores.cca: character version of the useful scalings are "sites" and "symmetric". See arguments correlation and hill.
correlation, hill: logical; additional arguments passed to predict.cca and predict.rda. See scores.cca for details.
rank: character; see argument of same name in function predict.cca or predict.rda.
join: character; the tpe of join to perform. See join for details of possible choices, but the default, "left" is most generally applicable.
object, x: an object of class "timetrack".
which: character; which fitted values should be returned?
model: character; which ordination component should be used for the fitted values; the constrained or unconstrained part? See fitted.cca for details, but essentially, one of "CCA" for the constrained part and "CA" for the unconstrained part. If NULL, the default, "CA" is used unless the underlying ordination was constrained, in which case "CCA" is used.
choices: numeric; the length-2 vector of ordination axes to plot.
newdata: a data frame of new observations for which locations in the plot (or a timetrack) are required. This need not have exactly the same set of species as the fitted ordination as internally only those species in newdata that were included in the data used for the ordination will be retained. In addition, if a transformation was applied to the species data used to fit the ordination, the same transformation will be automatically applied to newdata using tran.
display: character; which type of sites scores to display? See scores.cca for details.
order: numeric; vector of indices to use to reorder the passive samples. Useful to get passive samples into temporal order for plotting with a line.
type: character; the type of plotting required for the training set samples. Options are "p" for points or "n" to not draw training set samples.
ptype: character; controls how the time track should be drawn. Default is draw the passive samples connected by a line in the order in which they appear in the data. With ptype = "p" no line is drawn. The other types have their usual meaning from plot.default.
pch: The length-2 vector of plotting characters. The first element is used for the ordination samples, the second for the passive samples.
col: The length-2 vector of plotting colours. The first element is used for the ordination samples, the second for the passive samples.
lty, lwd: graphical parameters for the plotted time track for ptype != "p".
xlim, ylim: user specified axis limits for the plot.
...: arguments passed to other methods. timetrack passes arguments on to tran and the ordination function given in method. fitted passes arguments on to other fitted methods as appropriate. plot passes arguments on to the underlying plotting functions. predict passes arguments on to tran for use in applyign the transformation.

Author

Gavin L. Simpson

Details

The timetrack is a way to visualise changes in species composition from sediment core samples within an underlying reference ordination or, usually, training set samples. This technique has been most often applied in situations where the underlying ordination is a constrained ordination and thence the timetrack of sediment core samples within the ordination reflects both the change in species composition and the indicative changes in the constraining variables.

The sediment core samples are projected passively into the underlying ordination. By projected passively, the locations of the core samples are predicted on the basis of the ordination species scores. A common set of species (columns) is required to passively place the sediment samples into the ordination. To achieve this, the left outer join of the species compositions of the training set and passive set is determined; the left outer join results in the passive data matrix having the same set of species (variables; columns) as the training set. Any training set species not in the passive set are added to the passive set with abundance 0. Any passive species not in the training set are removed from the passive set.

Examples

Run this code

## load the RLGH and SWAP data sets
data(rlgh, swapdiat)

## Fit the timetrack ordination
mod <- timetrack(swapdiat, rlgh, transform = "hellinger",
                 method = "rda")
mod

## Plot the timetrack
plot(mod, ptype = "b", col = c("forestgreen", "orange"), lwd = 2)

## Other options (reorder the time track)
ord <- rev(seq_len(nrow(rlgh)))
plot(mod, choices = 2:3, order = ord, ptype = "b",
     col = c("forestgreen", "orange"), lwd = 2)

## illustrating use of the formula
data(swappH)
mod2 <- timetrack(swapdiat, rlgh, env = data.frame(pH = swappH),
                  transform = "hellinger", method = "rda",
                  formula = ~ pH)
mod2
plot(mod2)

## scores and fitted methods
## IGNORE_RDIFF_BEGIN
head(fitted(mod, type = "passive"))
head(scores(mod, type = "passive"))
## IGNORE_RDIFF_END

## predict locations in timetrack for new observations
take <- rlgh[1:50, ]
take <- take[ , colSums(take) > 0]
mod3 <- predict(mod, newdata = take)
class(mod3) ## returns a timetrack object
take <- rlgh[-(1:50), ]
take <- take[ , colSums(take) > 0]
mod4 <- predict(mod, newdata = take)

## build a plot up from base parts
plot(mod, type = "n", ptype = "n")
points(mod, which = "ordination", col = "grey", pch = 19, cex = 0.7)
points(mod3, which = "passive", col = "red")
points(mod4, which = "passive", col = "blue")

## Fit the timetrack ordination - passing scaling args
mod <- timetrack(swapdiat, rlgh, transform = "hellinger",
                 method = "rda", scaling = "sites",
                 correlation = TRUE)
mod
plot(mod)

Run the code above in your browser using DataLab