New version of permute on CRAN

Gavin Simpson

After some time brewing on my machines, I’m happy to have released a new version of my permute package for R. This release took quite a while to polish and get right as there was a lot of back-and-forth between vegan and permute as I tried to get the latter working nicely for both useRs and developers, whilst Jari worked on using the new permute API within vegan itself. All these changes were prompted by Cajo ter Braak taking me to task (nicely of course) over the use in previous versions of permute of the term “blocks” for what were not true blocking factors. Cajo challenged me to add true blocking factors (these restrict permutations within their levels and are never permuted, unlike plots), and the new version of permute is the result of my attempting to meet that challenge.

The changes to the design of permutations meant that I had to break code that used previous versions of permute and wasn’t something I did lightly. But it did need to be done. I took that opportunity to make the package easier to use too and decided I didn’t like typing permControl() each time I wanted to define a permutation design, resulting in the new how().

Version 0.8-0 represents a major update to permute, the salient details of which are given below, cropped from the new NEWS.Rd file. You can get the new version of permute now from CRAN.

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 function permControl().
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 old strata argument of how(). Blocks are specified via a new argument blocks, 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 names getFoo(), where Foo is a component of the design. Replacement functions have names setFoo. 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 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 new setFoo replacement functions should be used.
shuffleSet() is enhanced in this version. Firstly, the function now returns a classed object which has a print() method to allow for compact printing of the design elements used to generate the set of permutations. Second, shuffleSet() will sample nset permutations 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 of how().
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.