# how: How to define a permutation design? In permute: Functions for Generating Restricted Permutations of Data

## Description

Utility functions to describe unrestricted and restricted permutation designs for time series, line transects, spatial grids and blocking factors.

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11``` ```how(within = Within(), plots = Plots(), blocks = NULL, nperm = 199, complete = FALSE, maxperm = 9999, minperm = 5040, all.perms = NULL, make = TRUE, observed = FALSE) Within(type = c("free","series","grid","none"), constant = FALSE, mirror = FALSE, ncol = NULL, nrow = NULL) Plots(strata = NULL, type = c("none","free","series","grid"), mirror = FALSE, ncol = NULL, nrow = NULL) ```

## Arguments

 `within, plots, blocks` Permutation designs for samples within the levels of `plots` (`within`), permutation of `plots` themselves, or for the definition of blocking structures which further restrict permutations (`blocks`). `within` and `plots` each require a named list as produced by `Within` and `Plots` respectively. `blocks` takes a factor (or an object coercible to a factor via `as.factor`), the levels of which define the blocking structure. `nperm` numeric; the number of permutations. `complete` logical; should complete enumeration of all permutations be performed? `type` character; the type of permutations required. One of `"free"`, `"series"`, `"grid"` or `"none"`. See Details. `maxperm` numeric; the maximum number of permutations to perform. Currently unused. `minperm` numeric; the lower limit to the number of possible permutations at which complete enumeration is performed. When `nperm` is lower than `minperm`, sampling is performed from the set of complete permutations to avoid duplicate permutations. See argument `complete` and Details, below. `all.perms` an object of class `allPerms`, the result of a call to `allPerms`. `make` logical; should `check` generate all possible permutations? Useful if want to check permutation design but not produce the matrix of all permutations, or to circumvent the heuristics governing when complete enumeration is activated. `observed` logical; should the observed permutation be returned as part of the set of all permutations? Default is `FALSE` to facilitate usage in higher level functions. `constant` logical; should the same permutation be used within each level of strata? If `FALSE` a separate, possibly restricted, permutation is produced for each level of `strata`. `mirror` logical; should mirroring of sequences be allowed? `ncol, nrow` numeric; the number of columns and rows of samples in the spatial grid respectively. `strata` A factor, or an object that can be coerced to a factor via `as.factor`, specifying the strata for permutation.

## Details

`shuffle` can generate permutations for a wide range of restricted permutation schemes. A small selection of the available combinations of options is provided in the Examples section below.

Argument `mirror` determines whether grid or series permutations can be mirrored. Consider the sequence 1,2,3,4. The relationship between consecutive observations is preserved if we reverse the sequence to 4,3,2,1. If there is no inherent direction in your experimental design, mirrored permutations can be considered part of the Null model, and as such increase the number of possible permutations. The default is to not use mirroring so you must explicitly turn this on using `mirror = TRUE` in `how`.

To permute plots rather than the observations within plots (the levels of `strata`), use `Within(type = "none")` and `Plots(type = foo)`, where `foo` is how you want the plots to be permuted. However, note that the number of observations within each plot must be equal!

For some experiments, such as BACI designs, one might wish to use the same permutation within each plot. This is controlled by argument `constant`. If `constant = TRUE` then the same permutation will be generated for each level of `strata`. The default is `constant = FALSE`.

## Value

For `how` a list with components for each of the possible arguments.

Gavin Simpson

## References

`shuffle()` is modelled after the permutation schemes of Canoco 3.1 (ter Braak, 1990); see also Besag & Clifford (1989).

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).

`shuffle` and `shuffleSet` for permuting from a design, and `check`, a utility function for checking permutation design described by `how`.

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17``` ```## Set up factors for the Plots and Blocks plts <- gl(4, 10) ## 4 Plots of 10 samples each blks <- gl(2, 20) ## 2 Blocks of 20 samples each ## permutation design h1 <- how(within = Within(type = "series", mirror = TRUE), plots = Plots(strata = plts, type = "series"), blocks = blks) ## The design can be updated... ## ... remove the blocking: update(h1, blocks = NULL) ## ... or switch the type of shuffling at a level: #update(h1, plots = update(getPlots(h1), type = "none")) plots2 <- update(getPlots(h1), type = "none") update(h1, plots = plots2) ```

### Example output

```Permutation Design:

Blocks:
Defined by: none

Plots:
Plots: plts
Permutation type: series
Mirrored?: No

Within Plots:
Permutation type: series
Mirrored?: Yes
Different permutation within each Plot?: Yes

Permutation details:
Number of permutations: 199
Max. number of permutations allowed: 9999
Evaluate all permutations?: No.  Activation limit: 5040

Permutation Design:

Blocks:
Blocks: blks

Plots:
Plots: plts
Permutation type: none
Mirrored?: No

Within Plots:
Permutation type: series
Mirrored?: Yes
Different permutation within each Plot?: Yes

Permutation details:
Number of permutations: 199
Max. number of permutations allowed: 9999
Evaluate all permutations?: No.  Activation limit: 5040
```

permute documentation built on May 29, 2017, 11:21 a.m.