Forum: permute an R package for restricted permutations

Posted by: Gavin Simpson
Date: 2011-09-08 08:50
Summary: *permute* an R package for restricted permutations
Project: vegan - Community Ecology Package

Development Status : 5 - Production/Stable
Intended Audience : End Users/Desktop
License : GNU General Public License (GPL)
Natural Language : English
Operating System : OS Independent
Programming Language : C/C++ : Fortran : R
Topic : Environmetrics : Multivariate Statistics : Ecological Analysis

Content:

Yesterday, I rolled up the first public release of the *permute* package and submitted it to CRAN. This represents the first beta release of *permute* and presages significant changes to the way permutation tests are performed, and to the sorts of permutation available, in *vegan*.

*permute* allows the following permutation designs:

o free permutation (randomisation)
o permutation of spatial transect or time series data via cyclic wrapping
o permutation of spatial grids via toroidal wrapping

Each of these can be used at one or both of the block level and the within-block level. Blocks of samples are defined by the argument `strata` as has been used in *vegan* for many years. As such, *permute* allows for testing of split-plot designs. For spatial data (transect or grid), the cyclic or toroidal wrapping can be performed forwards or backwards in either spatial dimension, and the same permutation can be used for the samples in each block (for example, in the case a time series data where the samples in each block have been "exposed" to the same "time process").

The main functions in *permute* are the `shuffle()` and `shuffleSet()` functions which generate a single permutation or a set of many permutations for a stated design. Permutation designs are defined using function `permControl()`. Function `allPerms()` can be used to generate the entire set of permutations for a given design, which is useful if there are only a small number of permutations possible for the combination of permutation design and number of observations and/or complete enumeration (an exact test) is required.

With the release of *permute*, the older functions in *vegan* that implemented a previous version of these restricted permutations have been made defunct. Old code that utilised these functions should be ported to use the new functions in *permute*; help is available upon request. These changes are in *vegan* from version 2.0-0, which has also been released to CRAN.

The main reason for splitting the permutation code out from *vegan* was that by doing so we might make this code available to other package authors without having to depend on the entirety of *vegan*.

A nascent Vignette is provided with the package which aims to document the new functions and will, by version 0.8 include a section on using *permute* within functions for package authors wishing to make use of the functionality in *permute*.

If you have questions about or comments on the package, contact me or post a message in the Forums section of the R-forge website[1] for the *vegan* stable of packages/

Gavin Simpson

[1] https://r-forge.r-project.org/forum/?group_id=68