procrustes {vegan} | R Documentation

## Procrustes Rotation of Two Configurations and PROTEST

### Description

Function `procrustes` rotates a configuration to maximum similarity with another configuration. Function `protest` tests the non-randomness (`significance') between two configurations.

### Usage

    procrustes(X, Y, scale = TRUE, symmetric = FALSE, scores = "sites", ...)
    ## S3 method for class 'procrustes':
    summary(object, digits = getOption("digits"), ...)
    ## S3 method for class 'procrustes':
    plot(x, kind=1, choices=c(1,2), xlab, ylab, main,
         ar.col = "blue", len=0.05, ...)
    ## S3 method for class 'procrustes':
    points(x, display = c("target", "rotated"), ...)
    ## S3 method for class 'procrustes':
    lines(x, type = c("segments", "arrows"), choices = c(1, 2), ...)
    ## S3 method for class 'procrustes':
    residuals(object, ...)
    ## S3 method for class 'procrustes':
    fitted(object, truemean = TRUE, ...)
    protest(X, Y, scores = "sites", permutations = 1000, strata, ...)

### Arguments

`X` | Target matrix
`Y` | Matrix to be rotated.
`scale` | Allow scaling of axes of `Y`.
`symmetric` | Use symmetric Procrustes statistic (the rotation will still be non-symmetric).
`scores` | Kind of scores used. This is the `display` argument used with the corresponding `scores` function: see `scores`, `scores.cca` and `scores.cca` for alternatives.
`x, object` | An object of class `procrustes`.
`digits` | Number of digits in the output.
`kind` | For `plot` function, the kind of plot produced: `kind = 1` plots shifts in two configurations, `kind = 0` draws a corresponding empty plot, and `kind = 2` plots an impulse diagram of residuals.
`choices` | Axes (dimensions) plotted.
`xlab, ylab` | Axis labels, if defaults unacceptable.
`main` | Plot title, if default unacceptable.
`display` | Show only the `"target"` or `"rotated"` matrix as points.
`type` | Combine `target` and `rotated` points with line segments or arrows.
`truemean` | Use the original range of target matrix instead of centring the fitted values.
`permutations` | Number of permutation to assess the significance of the symmetric Procrustes statistic.
`strata` | An integer vector or factor specifying the strata for permutation. If supplied, observations are permuted only within the specified strata.
`ar.col` | Arrow colour.
`len` | Width of the arrow head.
`...` | Other parameters passed to functions. In `procrustes` and `protest` parameters are passed to `scores`, in graphical functions to underlying graphical functions.

### Details

Procrustes rotation rotates a matrix to maximum similarity with a target matrix minimizing sum of squared differences. Procrustes rotation is typically used in comparison of ordination results. It is particularly useful in comparing alternative solutions in multidimensional scaling. If `scale=FALSE`, the function only rotates matrix `Y`. If `scale=TRUE`, it scales linearly configuration `Y` for maximum similarity. Since `Y` is scaled to fit `X`, the scaling is non-symmetric. However, with `symmetric=TRUE`, the configurations are scaled to equal dispersions and a symmetric version of the Procrustes statistic is computed.

Instead of matrix, `X` and `Y` can be results from an ordination from which `scores` can extract results. Function `procrustes` passes extra arguments to `scores`, `scores.cca` etc. so that you can specify arguments such as `scaling`.

Function `plot` plots a `procrustes` object and returns invisibly an `ordiplot` object so that function `identify.ordiplot` can be used for identifying points. The items in the `ordiplot` object are called `heads` and `points` with `kind=1` (ordination diagram) and `sites` with `kind=2` (residuals). In ordination diagrams, the arrow heads point to the target configuration, which may be either logical or illogical. Target and original rotated axes are shown as cross hairs in two-dimensional Procrustes analysis, and with a higher number of dimensions, the rotated axes are projected onto plot with their scaled and centred range. Function `plot` passes parameters to underlying plotting functions. For full control of plots, you can draw the axes using `plot` with `kind = 0`, and then add items with `points` or `lines`. These functions pass all parameters to the underlying functions so that you can select the plotting characters, their size, colours etc., or you can select the width, colour and type of line `segments` or arrows, or you can select the orientation and head width of `arrows`.

Function `residuals` returns the pointwise residuals, and `fitted` the fitted values, either centred to zero mean (if `truemean=FALSE`) or with the original scale (these hardly make sense if `symmetric = TRUE`). In addition, there are `summary` and `print` methods.

If matrix `X` has a lower number of columns than matrix `Y`, then matrix `X` will be filled with zero columns to match dimensions. This means that the function can be used to rotate an ordination configuration to an environmental variable (most practically extracting the result with the `fitted` function).

Function `protest` calls `procrustes(..., symmetric = TRUE)` repeatedly to estimate the `significance' of the Procrustes statistic. Function `protest` uses a correlation-like statistic derived from the symmetric Procrustes sum of squares ss as r =sqrt{(1-ss)}, and sometimes called m_{12}. Function `protest` has own `print` method, but otherwise uses `procrustes` methods. Thus `plot` with a `protest` object yields a ``Procrustean superimposition plot.''

### Value

Function `procrustes` returns an object of class `procrustes` with items. Function `protest` inherits from `procrustes`, but amends that with some new items:

`Yrot` | Rotated matrix `Y`.
`X` | Target matrix.
`ss` | Sum of squared differences between `X` and `Yrot`.
`rotation` | Orthogonal rotation matrix.
`translation` | Translation of the origin.
`scale` | Scaling factor.
`symmetric` | Type of `ss` statistic.
`call` | Function call.
`t0` | This and the following items are only in class `protest`: Procrustes correlation from non-permuted solution.
`t` | Procrustes correlations from permutations.
`signif` | `Significance' of `t`
`permutations` | Number of permutations.
`strata` | The name of the stratifying variable.
`stratum.values` | Values of the stratifying variable.

### Note

The function `protest` follows Peres-Neto & Jackson (2001), but the implementation is still after Mardia et al. (1979).

### Author(s)

Jari Oksanen

### References

Mardia, K.V., Kent, J.T. and Bibby, J.M. (1979). Multivariate Analysis. Academic Press.

Peres-Neto, P.R. and Jackson, D.A. (2001). How well do multivariate data sets match? The advantages of a Procrustean superimposition approach over the Mantel test. Oecologia 129: 169-178.

### See Also

`isoMDS`, `initMDS` for obtaining objects for `procrustes`, and `mantel` for an alternative to `protest` without need of dimension reduction.

### Examples

    data(varespec)
    vare.dist <- vegdist(wisconsin(varespec))
    library(MASS)  ## isoMDS
    mds.null <- isoMDS(vare.dist, tol=1e-7)
    mds.alt <- isoMDS(vare.dist, initMDS(vare.dist), maxit=200, tol=1e-7)
    vare.proc <- procrustes(mds.alt, mds.null)
    vare.proc
    summary(vare.proc)
    plot(vare.proc)
    plot(vare.proc, kind=2)
    residuals(vare.proc)

[Package vegan version 1.8-6 Index]