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

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

Author: gsimpson
Date: 2013-11-30 20:47:02 +0100 (Sat, 30 Nov 2013)
New Revision: 2772

Modified:
   pkg/permute/vignettes/permutations.Rnw
Log:
add a more complex example of updating components of the design; some other tweaks and fixes for typos

Modified: pkg/permute/vignettes/permutations.Rnw
===================================================================
--- pkg/permute/vignettes/permutations.Rnw	2013-11-30 16:11:35 UTC (rev 2771)
+++ pkg/permute/vignettes/permutations.Rnw	2013-11-30 19:47:02 UTC (rev 2772)
@@ -432,6 +432,8 @@
     returns a logical, indicating whether the entire set of permutations should be produced or not.
   \item[\code{getObserved()}]
     returns a logical, which indicates whether the observed permutation (ordering of samples) is included in the entire set of permutation generated by \code{allPerms()}.
+  \item[\code{getAllperms()}]
+    extracts the complete set of permutations if present. Returns \code{NULL} if the set has not been generated.
 \end{description}
 
 The available \code{setFoo()<-} functions are
@@ -448,7 +450,7 @@
   \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.
+    replaces the \code{constant} 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<-()};]
@@ -481,10 +483,39 @@
 @
 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}.
 
+As a more complex example, consider the following design consisting of 5 blocks, each containing 2 plots of 5 samples each. Hence there are a total of 10 plots. Both the plots and within-plot sample are time series. This design can be created using
+<<get-set-eg3>>=
+hh <- how(within = Within(type = "series"),
+          plots = Plots(type = "series", strata = gl(10, 5)),
+          blocks = gl(5, 10))
+@
+
+To alter the design at the plot or within-plot levels, it is convenient to extract the relevant component using \code{getPlots()} or \code{getWithin()}, update the extracted object, and finally use the updated object to update \code{hh}. This process is illustrated below in order to change the plot-level permutation type to \code{"free"}
+<<get-set-eg4>>=
+pl <- getPlots(hh)
+setType(pl) <- "free"
+setPlots(hh) <- pl
+@
+We can confirm this has been changed by extracting the permutation type for the plot level
+<<get-set-eg5>>=
+getType(hh, which = "plots")
+@
+Notice too how the call has been expanded from \code{gl(10, 5)} to an integer vector. This expansion is to avoid the obvious problem of locating the objects referred to in the call should the call be re-evaluated later.
+<<get-set-eg6>>=
+getCall(getPlots(hh))
+@
+
+At the top level, a user can update the design using \code{update()}. Hence the equivalent of the above update (this time resetting the original type; \code{type = "series"})
+<<get-set-eg7>>=
+hh <- update(hh, plots = update(getPlots(hh), type = "series"))
+getType(hh, which = "plots")
+@
+This however is not guaranteed to work within a function, because we do not guarantee that components of the call used to create \code{hh} can be found from the execution frame where \code{update()} is called. To be safe, always use the \code{setFoo<-()} replacement functions to update design objects from within your functions.
+
 \section*{Computational details}
 This vignette was built within the following environment:
 <<seesionInfo, results=tex, echo=false>>=
-toLatex(sessionInfo())
+toLatex(sessionInfo(), locale = FALSE)
 @
 \bibliography{permute}
 \end{document}