permCheck {vegan} | R Documentation |

`permCheck`

provides checking of permutation schemes for
validity. `numPerms`

calculates the maximum number of
permutations possible under the current permutation
scheme. `allPerms`

enumerates all possible permutations for the
given scheme. `getNumObs`

is a utility function to return the
number of observations for a range of R and ordination
objects. `permuplot`

produces a graphical representation of the
selected permutation design.

permCheck(object, control = permControl(), make.all = TRUE) ## S3 method for class 'permCheck': summary(object, ...) numPerms(object, control = permControl()) allPerms(n, control = permControl(), max = 9999, observed = FALSE) ## S3 method for class 'allPerms': summary(object, ...) getNumObs(object, ...) ## Default S3 method: getNumObs(object, ...) ## S3 method for class 'numeric': getNumObs(object, ...) ## S3 method for class 'integer': getNumObs(object, ...) permuplot(n, control = permControl(), col = par("col"), hcol = "red", shade = "lightgrey", xlim = NULL, ylim = NULL, inset = 0.1, main = NULL, sub = NULL, ann = par("ann"), cex = par("cex"), ...)

`object` |
an R object. Specifically, for `getNumObs` any
object handled by `scores` , data frames, matrices, and
numeric and integer vectors. See Details for a complete
description, especially for `numPerms` . For
`summary.permCheck` an object of class
`"permCheck"` . For `summary.allPerms` an object of
class `"allPerms"` . |

`control` |
a list of control values describing properties of the
permutation design, as returned by a call to
`permControl` . |

`make.all` |
logical; should `permCheck` generate all
possible permutations? Useful if want to check permutation design
but not produce the matrix of all permutations. |

`n` |
the number of observations or an 'object' from which the
number of observations can be determined via `getNumObs` . |

`max` |
the maximum number of permutations, below which complete enumeration will be attempted. See Details. |

`observed` |
logical, should the observed ordering of samples be
returned as part of the complete enumeration? Default is
`FALSE` to facilitate usage in higher level functions. |

`col, xlim, ylim, main, sub, ann, cex` |
Graphical parameters. |

`hcol` |
Colour to use for highlighting observations and the border
colour of the polygons drawn when `type = "strata"` . |

`shade` |
The polygon shading colour (passed to argument `col`
of function `polygon` ) when `type = "strata"` . |

`inset` |
Proportion of range of x and y coordinates to add to the plot x and y limits. Used to create a bit of extra space around the margin of each plot. |

`...` |
arguments to other methods. For `permuplot`
graphical parameters can be passed to plotting functions, though
note that not all parameters will be accepted gracefully at the
moment. |

`permCheck`

, `allPerms`

, `numPerms`

and
`permuplot`

are utility functions for working with the new
permutation schemes available in `permuted.index2`

.

`permCheck`

is used to check the current permutation schemes
against the object to which it will be applied. It calculates the
maximum number of possible permutations for the number of observations
in `object`

and the permutation scheme described by
`control`

. The returned object contains component `control`

,
an object of class `"permControl"`

suitably modified if
`permCheck`

identifies a problem.

The main problem is requesting more permutations than possible with
the number of observations and the permutation design. In such cases,
`nperm`

is reduced to equal the number of possible permutations,
and complete enumeration of all permutations is turned on
(`control\$complete`

is set to `TRUE`

).

Alternatively, if the number of possible permutations is low, and less
than `control\$minperm`

, it is better to enumerate all possible
permutations, and as such complete enumeration of all permutations is
turned on (`control\$complete`

is set to `TRUE`

).

Function `numPerms`

returns the number of permutations for the
passed `object`

and the selected permutation
scheme. `object`

can be one of a data frame, matrix, an object
for which a scores method exists, or a numeric or integer vector. In
the case of a numeric or integer vector, a vector of length 1 can be
used and it will be expanded to a vector of length `object`

(i.e., `1:object`

) before computing the number of
permutations. As such, `object`

can be the number of observations
not just the object containing the observations.

Function `allPerms`

enumerates all possible permutations for the
number of observations and the selected permutation scheme. It has
`print`

and `summary`

methods. `allPerms`

returns a matrix containing all possible permutations, possibly
containing the observed ordering (if argument `observed`

is
`TRUE`

). The rows of this matrix are the various permutations and
the columns reflect the number of samples.

With free permutation designs, and restricted permutation schemes with
large numbers of observations, there are a potentially huge number of
possible permutations of the samples. It would be inefficient, not to
mention incredibly time consuming, to enumerate them all. Storing all
possible permutations would also become problematic in such cases. To
control this and guard against trying to evaluate too large a number
of permutations, if the number of possible permutations is larger than
`max`

, `allPerms`

exits with an error.

Function `getNumObs`

is a simple generic function to return the
number of observations in a range of R objects. The default method
will work for any object for which a `scores`

method
exists. This includes matrices and data frames, as well as specific
methods for numeric or integer vectors.

`permuplot`

is a graphical utility function, which produces a
graphical representation of a permutation design. It takes the number
of observations and an object returned by `permControl`

as
arguments and produces a plot on the currently active device. If
strata are present in the design, the plotting region is split into
sufficient plotting regions (one for each stratum), and the design in
each stratum plotted.

Free permutation designs are represented by plotting the observation
number at random x and y coordinates. Series designs (time series or
line transects) are represented by plotting the observation numbers
comprising the series in a circle and the start of the permuted series
is highlighted using colour `hcol`

. Grid designs are drawn on a
regular grid and the top left observation in the original grid is
highlighted using colour `hcol`

. Note the ordering used is R's
standard ordering for matrices - columns are filled first.

For `permCheck`

a list containing the maximum number of
permutations possible and an object of class
`"permControl"`

.

For `allPerms`

, and object of class `"allPerms"`

, a matrix
whose rows are the set of all possible permutations for the supplies
number of observations and permutation scheme selected. The matrix has
two additional attributes `control`

and
`observed`

. Attribute `control`

contains the argument
`control`

(possibly updated via `permCheck`

). Attribute
`observed`

contains argument `observed`

.

For `numPerms`

, the (numeric) number of possible permutations.

For `getNumObs`

, the (numeric) number of observations in
`object`

.

For `permuplot`

, a plot on the currently active device.

In general, mirroring `"series"`

or `"grid"`

designs doubles
or quadruples, respectively,the number of permutations without
mirroring (within levels of strata if present). This is **not**
true in two special cases:

- In
`"grid"`

designs where the number of columns is equal to 2, and - In
`"series"`

designs where the number of observations in a series is equal to 2.

For example, with 2 observations there are 2 permutations for
`"series"`

designs:

- 1-2, and
- 2-1.

If these two permutations were mirrored, we would have:

- 2-1, and
- 1-2.

It is immediately clear that this is the same set of permutations
without mirroring (if one reorders the rows). A similar situation
arises in `"grid"`

designs where the number of **columns**
per *grid* is equal to 2. Note that the number of rows per
*grid* is not an issue here.

Gavin Simpson

`permuted.index2`

and `permControl`

.

## use example data from ?pyrifos example(pyrifos) ## Demonstrate the maximum number of permutations for the pyrifos data ## under a series of permutation schemes ## no restrictions - lots of perms (check1 <- permCheck(pyrifos, control = permControl(type = "free"))) summary(check1) ## no strata but data are series with no mirroring, so 132 permutations permCheck(pyrifos, control = permControl(type = "series", mirror = FALSE)) ## no strata but data are series with mirroring, so 264 permutations permCheck(pyrifos, control = permControl(type = "series", mirror = TRUE)) ## unrestricted within strata permCheck(pyrifos, control = permControl(strata = ditch, type = "free")) ## time series within strata, no mirroring permCheck(pyrifos, control = permControl(strata = ditch, type = "series", mirror = FALSE)) ## time series within strata, with mirroring permCheck(pyrifos, control = permControl(strata = ditch, type = "series", mirror = TRUE)) ## time series within strata, no mirroring, same permutation within strata permCheck(pyrifos, control = permControl(strata = ditch, type = "series", constant = TRUE)) ## time series within strata, with mirroring, same permutation within strata permCheck(pyrifos, control = permControl(strata = ditch, type = "series", mirror = TRUE, constant = TRUE)) ## permute strata permCheck(pyrifos, permControl(strata = ditch, type = "free", permute.strata = TRUE)) ## this should also also for arbitrary vectors vec1 <- permCheck(1:100) vec2 <- permCheck(1:100, permControl()) all.equal(vec1, vec2) vec3 <- permCheck(1:100, permControl(type = "series")) all.equal(100, vec3$n) vec4 <- permCheck(1:100, permControl(type = "series", mirror = TRUE)) all.equal(vec4$n, 200) ## enumerate all possible permutations fac <- gl(2,6) ctrl <- permControl(type = "grid", mirror = FALSE, strata = fac, constant = TRUE, nrow = 3, ncol = 2) numPerms(1:12, control = ctrl) (tmp <- allPerms(12, control = ctrl, observed = TRUE)) (tmp2 <- allPerms(12, control = ctrl)) ## turn on mirroring ctrl$mirror <- TRUE numPerms(1:12, control = ctrl) (tmp3 <- allPerms(12, control = ctrl, observed = TRUE)) (tmp4 <- allPerms(12, control = ctrl)) ## prints out details of the permutation scheme as ## well as the matrix of permutations summary(tmp) summary(tmp2) ## different numbers of observations per level of strata fac <- factor(rep(1:3, times = c(3,2,2))) ## free permutations in levels of strata numPerms(7, permControl(type = "free", strata = fac)) allPerms(7, permControl(type = "free", strata = fac)) ## series permutations in levels of strata numPerms(7, permControl(type = "series", strata = fac)) allPerms(7, permControl(type = "series", strata = fac)) ## allPerms can work with a vector vec <- c(3,4,5) allPerms(vec) ## Tests for permuplot n <- 25 ## standard permutation designs permuplot(n, permControl(type = "free")) permuplot(n, permControl(type = "series")) permuplot(n, permControl(type = "grid", nrow = 5, ncol = 5)) ## restricted perms with mirroring permuplot(n, permControl(type = "series", mirror = TRUE)) permuplot(n, permControl(type = "grid", nrow = 5, ncol = 5, mirror = TRUE)) ## perms within strata fac <- gl(6, 20) control <- permControl(type = "free", strata = fac) permuplot(120, control = control, cex = 0.8) control <- permControl(type = "series", strata = fac) permuplot(120, control = control, cex = 0.8) fac <- gl(6, 25) control <- permControl(type = "grid", strata = fac, nrow = 5, ncol = 5) permuplot(150, control = control, cex = 0.8) ## perms within strata with mirroring fac <- gl(6, 20) control <- permControl(type = "series", strata = fac, mirror = TRUE) permuplot(120, control = control, cex = 0.8) fac <- gl(6, 25) control <- permControl(type = "grid", strata = fac, nrow = 5, ncol = 5, mirror = TRUE) permuplot(150, control = control, cex = 0.8) ## same perms within strata fac <- gl(6, 20) control <- permControl(type = "free", strata = fac, constant = TRUE) permuplot(120, control = control, cex = 0.8) control <- permControl(type = "series", strata = fac, constant = TRUE) permuplot(120, control = control, cex = 0.8) fac <- gl(6, 25) control <- permControl(type = "grid", strata = fac, nrow = 5, ncol = 5, constant = TRUE) permuplot(150, control = control, cex = 0.8) ## same perms within strata with mirroring fac <- gl(6, 20) control <- permControl(type = "series", strata = fac, mirror = TRUE, constant = TRUE) permuplot(120, control = control, cex = 0.8) fac <- gl(6, 25) control <- permControl(type = "grid", strata = fac, nrow = 5, ncol = 5, mirror = TRUE, constant = TRUE) permuplot(150, control = control, cex = 0.8)

[Package *vegan* version 1.16-32 Index]