cma {analogue}

Close modern analogues

Description

Extracts and formats close modern analogue samples from a modern reference set that are closer than a defined cut off threshold.

Usage

cma(object, ...)

## Default S3 method:
cma(object, ...)

## S3 method for class 'analog'
cma(object, cutoff, prob = c(0.01, 0.025, 0.05), ...)

## S3 method for class 'mat'
cma(object, k, cutoff, prob = c(0.01, 0.025, 0.05), ...)

## S3 method for class 'predict.mat'
cma(object, k, cutoff, prob = c(0.01, 0.025,
0.05), ...)

## S3 method for class 'cma'
plot(x, method = c("overplot", "jitter", "stack"),
   jitter = 0.1, vertical = FALSE,
   draw.quant = TRUE, xlab = NULL, ylab = "",
   main = "", cex.axis = NULL, ...,
   col.quant = "red", lty.quant= "dashed")

Arguments

object

an object for which close modern analogues are to be returned. Currently only for objects of class analog.

k

numeric; the number of analogues to return.

cutoff

numeric; critical value determining level below which samples from the modern reference set are defined as close modern analogues. May be missing, in which case the 2.5% quantile of the training set dissimilarities is used unless object$train is NULL, in which case "cutoff" must be supplied.

prob

numeric vector of probabilities with values in [0,1], for which quantiles of the distribution of training set dissimilarities will be calculated. See quantile.

...

arguments to be passed to other cma methods or additional arguments passed to stripchart.

x

an object of class "cma".

method

the method to be used to separate coincident points. The default method
"overplot" causes such points to be overplotted, but it is also possible to specify "jitter" to jitter the points, or "stack" have coincident points stacked. The last method only makes sense for very granular data.

jitter

when method="jitter" is used, jitter gives the amount of jittering applied.

vertical

when vertical is TRUE the plots are drawn vertically rather than the default horizontal.

draw.quant

logical; should the quantiles be drawn on the stripchart?

xlab, ylab, main

Graphical parameters

cex.axis

The magnification to be used for axis annotation relative to the current setting of cex. See par.

col.quant, lty.quant

colour and line type in which to drawn the quantile lines.

Details

The plot method is simply a wrapper to stripchart.

The methods for mat and predict.mat objects allow the user to select the k-closest analogues (argument k) or those samples as close or closer than a stated threshold of dissimilarity (argument cutoff). Only one of k and cutoff may be specified. If neither is specified, getK is used to extract the value for k stored within object. As such, the default is to return the automatically selected set of k closest samples, behaviour that is consistent with other functions in the package.

Value

For the plot method, a plot on the current device. Invisibly the plotted data are returned; see Note for further details.

A list of class "cma" with the following components:

close

a named list of named vectors of close modern analogues and their dissimilarities. The names of the list components are the names of the fossil samples. The named vector in each component of close is the distances for the close modern analogues from the training set that are as close as cutoff, or closer, to the fossil sample.

call

the matched call.

cutoff

the cutoff threshold used to define close modern analogues.

quant

numeric vector of the requested quantiles. Note returned by the predict.mat method.

probs

the probabilities of the requested quantiles.

method

character; the dissimilarity coefficient used

n.analogs

numeric vector of the number of analogues per fossil sample.

Note

Only objects of classes analog, mat, and predict.mat are supported.

The plot method invisibly returns a list with the following components:

• distancesa vector of stacked distances extracted from object.

• groupsa factor listing the fossil sample for which the distances are the distances to the close modern analogues for the training set.

Author(s)

Gavin L. Simpson

References

Flower, R.J., Juggins, S. and Battarbee, R.W. (1997) Matching diatom assemblages in lake sediment cores and modern surface sediment samples: the implications for lake conservation and restoration with special reference to acidified systems. Hydrobiologia 344; 27–40.

Simpson, G.L., Shilland, E.M., Winterbottom, J. M. and Keay, J. (2005) Defining reference conditions for acidified waters using a modern analogue approach. Environmental Pollution 137; 119–133.

See Also

analog, stripchart, or boxplot for an alternative representation.

Examples

## Imbrie and Kipp example
## load the example data
data(ImbrieKipp)
data(SumSST)
data(V12.122)

## merge training and test set on columns
dat <- join(ImbrieKipp, V12.122, verbose = TRUE)

## extract the merged data sets and convert to proportions
ImbrieKipp <- dat[[1]] / 100
V12.122 <- dat[[2]] / 100

## analog matching between SWAP and RLGH reference samples
(ik.ana <- analog(ImbrieKipp, V12.122, method = "chord"))

## close modern analogues
(ik.cma <- cma(ik.ana, cutoff = 0.4))
summary(ik.cma)

## plot the results
plot(ik.cma)