# Permute 3.1

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.

## Permute 3.1

These capabilities are provided by functions from the permutepackage. The user can request a particular type of permutation bysupplying the permutations argument of a function with anobject returned by how, which defines how samples shouldbe permuted. Alternatively, the user can simply specify the requirednumber of permutations and a simple randomisation procedure will beperformed. Finally, the user can supply a matrix of permutations (withnumber of rows equal to the number of permutations and number ofcolumns equal to the number of observations in the data) andvegan will use these permutations instead of generating newpermutations.

The Null hypothesis for the first two types of permutation test listedabove assumes free exchangeability of DATA (within the levelsof the grouping variable, if specified). Dependence betweenobservations, such as that which arises due to spatial or temporalautocorrelation, or more-complicated experimental designs, such assplit-plot designs, violates this fundamental assumption of the testand requires more complex restricted permutation test designs. It isthese designs that are available via the permute package and towhich vegan provides access from version 2.2-0 onwards.

The estimator described above is correct for the situation wherepermutations of the data are samples randomly withoutreplacement. This is not strictly what happens in vegan becausepermutations are drawn pseudo-randomly independent of oneanother. Note that the actual chance of this happening is practice issmall but the functions in permute do not guarantee to generatea unique set of permutations unless complete enumeration ofpermutations is requested. This is not feasible for all but thesmallest of data sets or restrictive of permutation designs, but insuch cases the chance of drawing a set of permutations with repeats islessened as the sample size, and thence the size of set of allpossible permutations, increases.

It is currently the responsibility of the user to determine the totalnumber of possible permutations for their DATA. The number ofpossible permutations allowed under the specified design can becalculated using numPerms from thepermute package. Heuristics employed within theshuffleSet function used by vegan can betriggered to generate the entire set of permutations instead of arandom set. The settings controlling the triggering of the completeenumeration step are contained within a permutation design createdusing link[permute]how and can be set by the user. Seehow for details.

Above, we have provided only a brief overview of the capbilities ofvegan and permute. To get the best out of the newfunctionality and for details on how to set up permutation designsusing how, consult the vignetteRestricted permutations; using the permute package suppliedwith permute and accessible via vignette("permutations", package = "permute").

permutest for the main interface in vegan. Seealso how for details on permutation designspecification, shuffleSet for the code used togenerate a set of permutations, numPerms fora function to return the size of the set of possible permutationsunder the current design.

When we provided a tabular illustration of the simple_books relation above, we noted that it was just one possible depiction of the relation. We can, for example, permute the rows of the table, without changing the relation. If we apply the second definition of tuple above, in which values are likewise not ordered but rather associated with specific attributes, it is valid to permute columns as well. We would say, then, that the illustration of simple_books below is equivalent to our previous illustration:

As in all statistical hypothesis tests, the significance of a permutation test is represented by its P-value. The P-value is the probability of obtaining a result at least as extreme as the test statistic given that the null hypothesis is true. In permutations tests, the null hypothesis is defined as: the labels assigning samples to classes are interchangeable (Edgington, 1980). Significantly, low P-values indicate that the labels are not interchangeable and that the original label configuration is relevant with respect to the data. The P-value is assessed by performing all possible permutations and computing the fraction of permutation values that are at least as extreme as the test statistic obtained from the unpermuted data.

Perform a partial permute of the first two arguments, which form a 32-bytesection of an emulated vector up to 256 bytes wide, using the partial permutecontrol vector in the third argument. The fourth argument (constrained tovalues of 0-7) identifies which 32-byte section of the emulated vector iscontained in the first two arguments.

Note that the use of resampling or permuting data in Step 2 involves randomness. Thus, the results of the procedure may depend on the obtained configuration of resampled/permuted values. Hence, it is advisable to repeat the procedure several (many) times. In this way, the uncertainty associated with the calculated variable-importance values can be assessed.