Utility functions to describe unrestricted and restricted permutation designs for time series, line transects, spatial grids and blocking factors.
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)
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.
numeric; the number of permutations.
logical; should complete enumeration of all permutations be performed?
character; the type of permutations required. One of
"free"
, "series"
, "grid"
or "none"
. See
Details.
numeric; the maximum number of permutations to perform. Currently unused.
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.
an object of class allPerms
, the result of a
call to allPerms
.
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.
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.
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
.
logical; should mirroring of sequences be allowed?
numeric; the number of columns and rows of samples in the spatial grid respectively.
A factor, or an object that can be coerced to a factor
via as.factor
, specifying the strata for permutation.
For how
a list with components for each of the possible arguments.
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 type controls how samples are actually permuted;
"free"
indicates randomization, "series"
indicates
permutation via cyclic shifts (suitable for evenly-spaced line
transect or time series data), "grid"
indicates permutation via
toroidal shifts (suitable for samples on a regular grid), and
"none"
indicates no permutation of samples. See the package
vignette (browseVignettes("permute")
) for additional
information on each of these types of permutation.
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
.
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
.
# NOT RUN {
## 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)
# }
Run the code above in your browser using DataLab