# New version of permute on CRAN version 0.8-0

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.