timetrack {analogue}

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 class 'timetrack'
fitted(object, which = c("passive", "ordination"),
       model = NULL, choices = 1:2, ...)

## S3 method for class 'timetrack'
predict(object, newdata, ...)

## S3 method for class 'timetrack'
scores(x, which = c("ordination", "passive"),
       scaling = x$scaling, choices = 1:2, display = "sites", ...)

## S3 method for class '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 class 'timetrack'
points(x, choices = 1:2, which = c("passive", "ordination"),
       display = c("wa","lc"), order, ...)

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.

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.

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.

Author(s)

Gavin L. Simpson

See Also

cca and rda for the underlying ordination functions.

Examples

## 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)