permute
Functions for Generating Restricted Permutations of Data
A set of restricted permutation designs for freely exchangeable, line transects (time series), and spatial grid designs plus permutation of blocks (groups of samples) is provided. 'permute' also allows split-plot designs, in which the whole-plots or split-plots or both can be freely-exchangeable or one of the restricted designs. The 'permute' package is modelled after the permutation schemes of 'Canoco 3.1' (and later) by Cajo ter Braak.
Released version
Build status
What is permute?
permute generates permutations from a range of restricted permutation designs.
Permute provides an R implementation of the permutation schemes developed by Cajo ter Braak and made available in the Canoco software, version 3.1 (ter Braak, 1990). These permutation schemes draw upon ideas from an earlier paper by Besag & Clifford (1989).
Several types of permutation are available in permute:
- Free permutation of objects
- Time series or line transect designs, where the temporal or spatial ordering is preserved.
- Spatial grid designs, where the spatial ordering is preserved in both coordinate directions
- Permutation of plots or groups of samples.
- Blocking factors which restrict permutations to within blocks. The preceding designs can be nested within blocks, allowing analysis of hierachical designs (e.g. split plot designs)
References
Besag, J. and Clifford, P. (1989) Generalized Monte Carlo significance tests. Biometrika 76; 633–642.
ter Braak, C. J. F. (1990). Update notes: CANOCO version 3.1. Wageningen: Agricultural Mathematics Group. (UR).
News
permute News
Changes in version 0.9-4
The example in ?check was made to suppress package startup messages from vegan.
Changes in version 0.9-3
This release fixed some non-canonical-form CRAN URLs.
Changes in version 0.9-2
This release was purely to avoid issues with CRAN as a new release of vegan had been released and the example reference material hadn't been updated to match.
Changes in version 0.9-1
General
A minor bug fix release to address a single problem.
Bug Fixes
shuffleSet()wasn't returning a matrix ifnset = 1andallPermswas invoked because of a low set of possible permutations. GitHub Issue #19
Changes in version 0.9-0
General
This is small update to permute, focused mainly on ensuring the many combinations of restrictions on permutations allowed by the package work. An extensive test suite has been written which covers ~87% of the package's codebase at the time of release.
New features
-
Permutation matrices produced by
shuffleSet()are now printed in a more compact form. -
Better heuristics in
check()allow for more reliable permutations (i.e. fewer duplicate permutations) when the set is small. This has increased theminpermssetting. Consequently we generate all possible permutations up to ~500,000 more often as we now randomly sample from the entirely generated set rather than randomly generate permutations. This provides a small performance hit in some rare cases. -
shuffleSet()has a new argumentquietly = FALSEwhich is passed on tocheck(). -
A number of bugs were fixed. See the Changelog and the Bug reports on github for details.
Defunct
permControl()andpermuplot()are defunct and have been removed from the package.
Changes in version 0.8-0
General
- Version 0.8-0 represents a major update of permute, with some backwards-incompatible changes to the main functions. The main addition is the availability of block-level restrictions on the permutations, which are required for whole- and split-plot designs.
New features
-
how(), a new function to create permutation designs. This replaces the deprecated functionpermControl. -
permute gains the addition of true blocking structures with which to restrict the permutations. Blocks sit as the outermost layer of the permutations, and can contain plots which in turn contain samples. In contrasts to plots, blocks are never permuted and samples are never shuffled between blocks. Permutation only ever happens within blocks.
To facilitate this, plot-level strata are now specified via
Plots()instead of via the oldstrataargument ofhow(). Blocks are specified via a new argumentblocks, which takes a factor variable. -
A new suite of extractor and replacement functions is provided with which to interact with permutation designs created by
how(). Extractor functions have namesgetFoo(), whereFoo()is a component of the design. Replacement functions have namessetFoo`. The replacement function are especially for use by package authors wishing to alter permutation within their functions. The extractor functions are recommended for all users wishing to extract features of the permutation design. -
As a convenience for users, the \code{update()} function will now work with objects of classes
"how","Plots"or"Within"to allow quick updating of features of the permutation design. This approach is intended for interactive use at the top-level and not within functions, where the newsetFooreplacement functions should be used. -
shuffleSet()is enhanced in this version. Firstly, the function now returns a classed object which has aprint()method to allow for compact printing of the design elements used to generate the set of permutations. Second,shuffleSet()will samplensetpermutations from the entire set of permutations should a small number of possible permutations trigger generation of the entire set. This avoids the generation of a set of non-unique permutations. Finally the random seed that generated the set is stored as an attribute. -
allPerms()no longer assumes that samples are in block and/or plot ordering. -
The package vignette is much expanded in this version with new sections on using permute within functions that will be of interest to package authors wishing to use permute in their packages.
Deprecated
-
permControl()is deprecated in favour ofhow(). -
permuplot()is broken and effectively defunct given the changes to the way permutation are defined and the addition of blocks.permuplot()is no longer exported from the package namespace.