[R-sig-eco] [pkg] *permute* an R package for restricted permutations

[Gavin Simpson]

Dear List,

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:

      * free permutation (randomisation) 
      * permutation of spatial transect or time series data via cyclic
        wrapping 
      * 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 of time
series data where the samples in each block have been "exposed" to the
same "time process").

An major aim in writing *permute* has been to provide functionality
found in the widely-used, commercial application Canoco.

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
-- 
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
 Dr. Gavin Simpson             [t] +44 (0)20 7679 0522
 ECRC, UCL Geography,          [f] +44 (0)20 7679 0565
 Pearson Building,             [e] gavin.simpsonATNOSPAMucl.ac.uk
 Gower Street, London          [w] http://www.ucl.ac.uk/~ucfagls/
 UK. WC1E 6BT.                 [w] http://www.freshwaters.org.uk
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%