# Permutation test for predictive co-correspondence analysis models

### Description

A permutation test for predictive co-correspondence analysis models to assess the significance of each CoCA ordination axes.

### Usage

1 2 3 4 5 6 7 8 |

### Arguments

`x` |
an object of class |

`R0` |
row weights to use in the analysis. If missing, the
default, these are determined from |

`permutations` |
the number of permutations to perform. |

`n.axes` |
The number of axes to test. Defaults to the number of
axes stated in |

`verbose` |
if |

`object` |
an object of class |

`...` |
arguments to be passed to other methods. |

### Details

An alternative approach to cross-validation (see
`crossval`

) to select the number of axes to retain in a
predictive co-correspondence analysis is to test the statistical
significance of each ordination axis using permutation tests.

The test statistic used is the *F*-ratio based on the fit of the
first axis to the response data (ter Braak and Smilauer 2002). The
second and subsequent axes are tested by treating previous axes as
co-variables.

To be precise, this approach does not test the significance of SIMPLS axes, but those of NIPALS-PLS axes (ter Braak and de Jong 1998).

### Value

A list with the following components:

`pval ` |
a vector of |

`permstat ` |
a vector of values for the test statistic for each axis. |

`total.inertia ` |
the total inertia in the response matrix. |

`inertia ` |
a vector containing the inertia explained by each ordination axis. |

`fitax ` |
a vector containing the fit of each axis to response. |

`pcent.fit ` |
a vector containing the fit of each axis to the response as a percentage of the total inertia (variance). |

`n.axes ` |
the number of axes in the ordination. |

`call ` |
the matched call. |

### Warning

This function is **slow**. Beware setting argument
`permutations`

higher than the default. Determine how long it
takes for the default 99 permutations to complete before going crazy
and asking for thousands of permutations - you've been warned, have a
good book to hand.

### Note

Argument `R0`

is provided for compatibility with the original
MATLAB code. The R usage paradigm makes this argument redundant in the
current code and it may be invalid to supply different row weights
(*R_0*) as `R0`

. This argument will likely be removed in future
versions.

### Author(s)

Gavin L. Simpson, based on Matlab code by C.J.F. ter Braak and A.P. Schaffers.

### References

ter Braak, C.J.F. and de Jong, S. (1998) The objective function of
partial least squares regression. *Journal of Chemometrics*
**12**, 41–54.

ter Braak, C.J.F and Schaffers, A.P. (2004) Co-Correspondence
Analysis: a new ordination method to relate two community
compositions. *Ecology* **85(3)**, 834–846.

ter Braak, C.J.F. and Smilauer, P. (2002) *Canoco reference manual
and CanoDraw for Windows user's guide: software for canonical
community ordination. Version 4.5*. New York: Microcomputer Power.

### See Also

`coca`

, for the model fitting function,
`crossval`

, for a leave-one-out cross-validation
procedure, which is the preferred way to select axes in a predictive
co-correspondence analysis.

### Examples

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | ```
## load some data
data(beetles)
data(plants)
## log transform the bettle data
beetles <- log(beetles + 1)
## predictive CoCA using SIMPLS and formula interface
bp.pred <- coca(beetles ~ ., data = plants)
## should retain only the useful PLS components for a parsimonious model
## Not run:
## Leave-one-out crossvalidation - this takes a while
crossval(beetles, plants)
## so 2 axes are sufficient
## permutation test to assess significant PLS components - takes a while
bp.perm <- permutest(bp.pred, permutations = 99)
bp.perm
summary(bp.perm)
## End(Not run)
## permutation test, this time only testing the first 2 axes
bp.perm <- permutest(bp.pred, permutations = 75, n.axes = 2)
bp.perm
``` |