[Vegan-commits] r2664 - in pkg/permute: R inst man vignettes
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Thu Nov 7 22:15:06 CET 2013
Author: gsimpson
Date: 2013-11-07 22:15:05 +0100 (Thu, 07 Nov 2013)
New Revision: 2664
Modified:
pkg/permute/R/shuffleSet2.R
pkg/permute/inst/ChangeLog
pkg/permute/man/shuffleSet.Rd
pkg/permute/vignettes/permutations.Rnw
Log:
allow checking in shuffleSet to be controlled via the user; adds argument check defaulting to TRUE.
Modified: pkg/permute/R/shuffleSet2.R
===================================================================
--- pkg/permute/R/shuffleSet2.R 2013-11-07 04:21:56 UTC (rev 2663)
+++ pkg/permute/R/shuffleSet2.R 2013-11-07 21:15:05 UTC (rev 2664)
@@ -1,5 +1,5 @@
## new version of shuffleSet() that allows for blocking
-`shuffleSet` <- function(n, nset, control = how()) {
+`shuffleSet` <- function(n, nset, control = how(), check = TRUE) {
## handle missing nset - take from control if can
if(missing(nset)) {
np <- getNperm(control)
@@ -11,10 +11,17 @@
sn <- seq_len(n) ## sequence of samples in order of input
- ## need to check number of permutations won't blow up
- pcheck <- check(sn, control = control, make.all = TRUE)
- ## control possibly now updated
- control <- pcheck$control
+ ## if checking permutation design, may end up with more perms
+ ## than requested in nset, depending upon what user specified
+ ## in `control`. The `check` argument can turn this step off
+ ## so you always get `nset` permutations and, yes, you can shoot
+ ## yourself in the foot with this, hence the dfeualt is to check!
+ if (isTRUE(check)) {
+ ## need to check number of permutations won't blow up
+ pcheck <- check(sn, control = control, make.all = TRUE)
+ ## control possibly now updated
+ control <- pcheck$control
+ }
if(is.null(control$all.perms)) {
## get blocking, if any
Modified: pkg/permute/inst/ChangeLog
===================================================================
--- pkg/permute/inst/ChangeLog 2013-11-07 04:21:56 UTC (rev 2663)
+++ pkg/permute/inst/ChangeLog 2013-11-07 21:15:05 UTC (rev 2664)
@@ -15,6 +15,14 @@
permutations.
Reported by Jari Oksanen.
+ Gains an argument, `check`, which allows the user to control whether
+ the permutation design should be checked. In small data sets or where
+ there are very few permutations, `shuffleSet` could generate more
+ permutations (i.e. all possible ones) than requested. Turning off this
+ checking with `check = FALSE` will result in exactly `nset`
+ permutations being returned, but without a gaurantee that they will
+ be unique.
+
* numPerms: fixed a bug where `numPerms()` was ignoring Blocks when
computing the number of possible permutations.
Modified: pkg/permute/man/shuffleSet.Rd
===================================================================
--- pkg/permute/man/shuffleSet.Rd 2013-11-07 04:21:56 UTC (rev 2663)
+++ pkg/permute/man/shuffleSet.Rd 2013-11-07 21:15:05 UTC (rev 2664)
@@ -11,7 +11,7 @@
set of permutations.
}
\usage{
-shuffleSet(n, nset, control = how())
+shuffleSet(n, nset, control = how(), check = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
@@ -24,12 +24,43 @@
\code{control}.
}
\item{control}{
- an object of class \code{"how"} describing a valid
- permutation design.
+ an object of class \code{"how"} describing a valid permutation
+ design.
}
+ \item{check}{
+ logical; should the design be checked for various problems via
+ function \code{\link{check}}? The default is to check the design for
+ the stated number of observations and update \code{control}
+ accordingly. See Details.
+ }
}
\details{
- TODO
+ \code{shuffleSet} is designed to generate a set of \code{nset}
+ permutation indices over which a function can iterate as part of a
+ permutation test. It is only slightly more efficient than calling
+ \code{\link{shuffle}} \code{nset} times, but it is far more practical
+ than the simpler function because a set of permutations can be worked
+ on by applying a function to the rows of the returned object. This
+ simplifies the function applied, and facilitates the use of parallel
+ processing functions, thus enabling a larger number of permutations to
+ be evaluated in reasonable time.
+
+ By default, \code{shuffleSet} will check the permutations design
+ following a few simple heuristics. See \code{\link{check}} for details
+ of these. Whether some of the heuristics are activiated or not can be
+ controlled via \code{\link{how}}, essentialy via its argument
+ \code{minperm}. In particular, if there are fewer than \code{minperm}
+ permutations, \code{shuffleSet} will generate and return \strong{all
+ possible permutations}, which may differ from the number requested via
+ argument \code{nset}.
+
+ The \code{check} argument to \code{shuffleSet} controls whether
+ checking is performed in the permutation design. If you set
+ \code{check = FALSE} then exactly \code{nset} permutations will be
+ returned. However, do be aware that there is no guarantee that the set
+ of permutations returned will be unique, especially so for designs and
+ data sets where there are few possible permutations relative to the
+ number requested.
}
\value{
Returns a matrix of permutations, where each row is a separate
@@ -46,7 +77,7 @@
%% ~Make other sections like Warning with \section{Warning }{....} ~
\references{
- \code{shuffle()} is modelled after the permutation schemes of Canoco
+ \code{shuffleSet()} 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
@@ -61,10 +92,11 @@
}
\examples{
## simple random permutations, 5 permutations in set
-shuffleSet(n = 10, nset = 10)
+shuffleSet(n = 10, nset = 5)
-## series random permutations, 10 permutations in set
-shuffleSet(10, 10, how(within = Within(type = "series")))
+## series random permutations, 5 permutations in set
+shuffleSet(10, 5, how(within = Within(type = "series")),
+ check = FALSE)
## series random permutations, 10 permutations in set,
## with possible mirroring
@@ -94,7 +126,7 @@
## as above, but with same permutation for each Plot-level stratum
CTRL <- how(plots = plotStrata,
within = Within(type = "series", constant = TRUE))
-shuffleSet(20, 10, CTRL)
+shuffleSet(20, 10, CTRL, check = FALSE)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
Modified: pkg/permute/vignettes/permutations.Rnw
===================================================================
--- pkg/permute/vignettes/permutations.Rnw 2013-11-07 04:21:56 UTC (rev 2663)
+++ pkg/permute/vignettes/permutations.Rnw 2013-11-07 21:15:05 UTC (rev 2664)
@@ -242,9 +242,10 @@
<<shuffleSet_1, keep.source=true>>=
set.seed(4)
CTRL <- how(within = Within(type = "series"))
-pset <- shuffleSet(10, nset = 5, control = CTRL)
+pset <- shuffleSet(10, nset = 5, control = CTRL, check = FALSE)
pset
@
+Note that we set \code{check = FALSE} in the call. As there are only 10 permutations of these data (including the observed one), by default \code{shuffleSet()} will check the permutation design and, following a few heuristics\footnote{Values used in these heuristics can be set when you create the permutation design with \code{how()}. See \code{?how} for further details and \code{?check} for the function that does the checking.}, will in this case generate all ten permutations. Setting \code{check = FALSE} turns this checking off, enabling exactly \code{nset} permutations to be returned. The downside of this is that you need to be aware of the implications of not checking the design; with a limited number of possible permutations, there is no guarantee that \code{shuffleSet()} will generate a set of \code{nset} unique permutations.
\section{Defining permutation designs}
In this section examples are given of how various permutation designs can be specified using \code{how()}. It is not the intention to provide exhaustive coverage of all possible designs that can be produced; such a list would be tedious to both write \emph{and} read. Instead, the main features and options will be described through a series of examples. The reader should then be able to put together the various options to create the exact structure required.
More information about the Vegan-commits
mailing list