permCheck: Utility functions for permutation schemes

Description

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.

Usage

permCheck(object, control = permControl(), make.all = TRUE)
## S3 method for class 'permCheck':
summary(object, \dots)
numPerms(object, control = permControl())
allPerms(n, control = permControl(), max = 9999,
         observed = FALSE)
## S3 method for class 'allPerms':
summary(object, \dots)
getNumObs(object, ...)
## S3 method for class 'default':
getNumObs(object, \dots)
## S3 method for class 'numeric':
getNumObs(object, \dots)
## S3 method for class 'integer':
getNumObs(object, \dots)
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"), ...)

Arguments

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

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.

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.

Value

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.

Details

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.

Examples

Run this code

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