| 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:
"grid" designs where the number of columns is equal
to 2, and
"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:
If these two permutations were mirrored, we would have:
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 = "strata"))
## 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)
## permute strata
fac <- factor(rep(1:6, each = 20), labels = paste("Ditch", 1:6))
permuplot(length(fac), permControl(strata = fac, type = "strata"))