[Vegan-commits] r2760 - pkg/permute/vignettes

[noreply at r-forge.r-project.org]

Author: gsimpson
Date: 2013-11-26 05:57:32 +0100 (Tue, 26 Nov 2013)
New Revision: 2760

Modified:
   pkg/permute/vignettes/permutations.Rnw
   pkg/permute/vignettes/permute.bib
Log:
Updates to the vignette; mainly adding the new setFoo functions

Modified: pkg/permute/vignettes/permutations.Rnw
===================================================================
--- pkg/permute/vignettes/permutations.Rnw	2013-11-26 04:56:32 UTC (rev 2759)
+++ pkg/permute/vignettes/permutations.Rnw	2013-11-26 04:57:32 UTC (rev 2760)
@@ -59,7 +59,7 @@
 
 An alternative to deriving the null distribution from theory is to generate a null distribution of the test statistic by randomly shuffling the data in some manner, refitting the model and deriving values for the test statistic for the permuted data. The level of significance of the test can be computed as the proportion of values of the test statistic from the null distribution that are equal to or larger than the observed value.
 
-In many data sets, simply shuffling the data at random is inappropriate; under the null hypothesis, that data are not freely exchangeable, for example if there is temporal or spatial correlation, or the samples are clustered in some way, such as multiple samples collected from each of a number of fields. The \pkg{permute} package was designed to provide facilities for generating these restricted permutations for use in randomisation tests.
+In many data sets, simply shuffling the data at random is inappropriate; under the null hypothesis, that data are not freely exchangeable, for example if there is temporal or spatial correlation, or the samples are clustered in some way, such as multiple samples collected from each of a number of fields. The \pkg{permute} package was designed to provide facilities for generating these restricted permutations for use in randomisation tests. \pkg{permute} takes as its motivation the permutation schemes originally available in \proglang{Canoco} version 3.1 \citep{canoco31}, which employed the cyclic- or toroidal-shifts suggested by \citet{besagclifford}.
 
 \section{Simple randomisation}\label{sec:simple}
 As an illustration of both randomisation and simple usage of the \pkg{permute} package we consider a small data set of mandible length measurements on specimens of the golden jackal (\emph{Canis aureus}) from the British Museum of Natural History, London, UK. These data were collected as part of a study comparing prehistoric and modern canids \citep{higham80}, and were analysed by \citet{manly07}. There are ten measurements of mandible length on both male and female specimens. The data are available in the \code{jackal} data frame supplied with \pkg{permute}.
@@ -434,25 +434,37 @@
     returns a logical, which indicates whether the observed permutation (ordering of samples) is included in the entire set of permutation generated by \code{allPerms()}.
 \end{description}
 
-At the moment, the range of \code{setFoo()<-} functions is not as comprehensive as for the \code{getFoo()} functions. The available \code{setFoo()<-} functions are
+The available \code{setFoo()<-} functions are
 
 \begin{description}
-  \item[\code{setBlocks()<-};]
+  \item[\code{setPlots<-()}, \code{setWithin<-()};]
+    replaces the details of the \emph{within}-, and \emph{plots}-, components of the design. The replacement object must be of class \code{"Plots"} or \code{"Within"}, respectively, and hence is most usefully used in combination with the \code{Plots()} or \code{Within()} constructor functions.
+  \item[\code{setBlocks<-()};]
     replaces the factor that partitions the observations into blocks. \code{value} can be any \proglang{R} object that can be coerced to a factor vector via \code{as.factor()}.
-  \item[\code{setNperm()<-}, \code{setMinperm<-()}, \code{setMaxperm<-()};]
-    update the stored values for the requested number of permutations and the minimum and maximum permutation thresholds that control whether the entire set of permutations is generated instead of the \code{nperm} permutations.
-  \item[\code{setAllperms()<-};]
+  \item[\code{setStrata<-()};]
+    replaces either the \code{blocks} or \code{strata} components of the design, depending on what class of object \code{setStrata<-()} is applied to. When used on an object of class \code{"how"}, \code{setStrata<-()} replaces the \code{blocks} component of that object. When used on an object of class \code{"Plots"}, \code{setStrata<-()} replaces the \code{strata} component of that object. In both cases a factor variable is required and the replacement object will be coerced to a factor via \code{as.factor()} if possible.
+  \item[\code{setType<-()};]
+    replaces the \code{type} component of an object of class \code{"Plots"} or \code{"Within"} with a character vector of length one. Must be one of the available types: \code{"none"}, \code{"free"}, \code{"series"}, or \code{"grid"}.
+  \item[\code{setMirror<-()};]
+    replaces the \code{mirror} component of an object of class \code{"Plots"} or \code{"Within"} with a logical vector of length one.
+  \item[\code{setConstant<-()};]
+    replaces the \code{mirror} component of an object of class \code{"Within"} with a logical vector of length one.
+  \item[\code{setRow<-()}, \code{setCol<-()}, \code{setDim<-()};]
+    replace one or both of the spatial grid dimensions of an object of class \code{"Plots"} or \code{"Within"} with am integer vector of length one, or, in the case of \code{setDim<-()}, of length 2.
+  \item[\code{setNperm<-()}, \code{setMinperm<-()}, \code{setMaxperm<-()};]
+    update the stored values for the requested number of permutations and the minimum and maximum permutation thresholds that control whether the entire set of permutations is generated instead of \code{nperm} permutations.
+  \item[\code{setAllperms<-()};]
     assigns a matrix of permutation indices to the \code{all.perms} component of the design list object.
-  \item[\code{setComplete()<-};]
+  \item[\code{setComplete<-()};]
     updates the status of the \code{complete} setting. Takes a logical vector of length 1 or any object coercible to such.
-  \item[\code{setMake()<-};]
+  \item[\code{setMake<-()};]
     sets the indicator controlling whether the entrie set of permutations is generated during checking of the design via \code{check()}. Takes a logical vector of length 1 or any object coercible to such.
-  \item[\code{setObserved()<-};]
+  \item[\code{setObserved<-()};]
     updates the indicator of whether the observed ordering is included in the set of all permutations should they be generated. Takes a logical vector of length 1 or any object coercible to such.
 \end{description}
 
 \subsubsection{Examples}
-I illustrate the behaviour of the \code{getFoo()} and \code{setFoo<-()} functions through a couple of simple examples. Firstly, generate or design object
+I illustrate the behaviour of the \code{getFoo()} and \code{setFoo<-()} functions through a couple of simple examples. Firstly, generate a design object
 <<get-set-eg0>>=
 hh <- how()
 @
@@ -467,9 +479,11 @@
 getNperm(hh)
 getCall(hh)
 @
+Note how the \code{call} component has been altered to include the argument pair \code{nperm = 999}, hence if this call were evaluated, the resulting object would be a copy of \code{hh}.
 
 \section*{Computational details}
-<<seesionInfo, results=tex>>=
+This vignette was built within the following environment:
+<<seesionInfo, results=tex, echo=false>>=
 toLatex(sessionInfo())
 @
 \bibliography{permute}

Modified: pkg/permute/vignettes/permute.bib
===================================================================
--- pkg/permute/vignettes/permute.bib	2013-11-26 04:56:32 UTC (rev 2759)
+++ pkg/permute/vignettes/permute.bib	2013-11-26 04:57:32 UTC (rev 2760)
@@ -30,4 +30,22 @@
   year = {2013},
   note = {R package version 2.1-33},
   url = {http://vegan.r-forge.r-project.org/}
-}
\ No newline at end of file
+}
+
+ at Manual{canoco31,
+  title = 	 {Update notes: CANOCO version 3.1},
+  author = 	 {ter Braak, C.J.F.},
+  organization = {Wageningen: Agricultural Mathematics Group},
+  year = 	 {1990}
+}
+
+ at Article{besagclifford,
+  author = 	 {Besag, J. and Clifford, P.},
+  title = 	 {Generalized Monte Carlo significance tests},
+  journal = 	 {Biometrika},
+  year = 	 {1989},
+  volume = 	 {76},
+  number = 	 {4},
+  pages = 	 {633--642}
+}
+