procrustes               package:vegan               R Documentation

_P_r_o_c_r_u_s_t_e_s _R_o_t_a_t_i_o_n _o_f _T_w_o _C_o_n_f_i_g_u_r_a_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     procrustes(X, Y, scale = TRUE, symmetric = FALSE)
     ## S3 method for class 'procrustes':
     summary(object, ...)
     ## 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, permutations = 1000, strata)

_A_r_g_u_m_e_n_t_s:

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

x, object: An object of class 'procrustes'.

    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.

_D_e_t_a_i_l_s:

     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 '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.  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 youc an 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.''

_V_a_l_u_e:

     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.

_N_o_t_e:

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

_A_u_t_h_o_r(_s):

     Jari Oksanen

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

     data(varespec)
     vare.dist <- vegdist(wisconsin(varespec))
     library(MASS)  ## isoMDS
     library(mva)   ## cmdscale to start isoMDS
     mds.null <- isoMDS(vare.dist, tol=1e-7)
     ## This was a good seed for me: your rng may vary.
     set.seed(237)
     mds.alt <- isoMDS(vare.dist, initMDS(vare.dist), maxit=200, tol=1e-7)
     vare.proc <- procrustes(mds.alt$points, mds.null$points)
     vare.proc
     summary(vare.proc)
     plot(vare.proc)
     plot(vare.proc, kind=2)
     residuals(vare.proc)
     ## Reset rng:
     rm(.Random.seed)

