permute ChangeLog Version 0.9-1 * setAllperms<-.how() was stripping the "allPerms" class. (#16) Reported by: @brendanf * nobs: added a `nobs.character` method (#17) * get-methods: added a `getControl()` extractor with a default method and a method for class `"check"`. There is an alias in the form of `getHow()` (#18) * shuffle: now accepts objects from which we derive the number of observations, bringing is into line with `shuffleSet()` Version 0.9-0 * Release to CRAN 23 Jan 2016 Version 0.8-5 * shuffleSet gains new argument `quietly = FALSE`, which is passed on to `check()` to allow control over printing of statements during checking. Reported by: (and fixed by) Jari Oksanen * allPerms would return a vector instead of a matrix when a single permutation was generated. Reported by: (and fixed by) Jari Oksanen * Better defaults for `check()` heuristics allow for more reliable (i.e. fewer duplicate permutations) permutations when the set of permutations is small. Provided by: Jari Oksanen * allStrata did not handle cases where strata were not in contiguous blocks: e.g. `c(1, 2, 3, 1, 2, 3)` vs `c(1, 1, 2, 2, 3, 3)` Reported by: David Warton * Permutation matrices returned by `shuffleSet()` now print the permutations more compactfully. * as.matrix.allPerms: new S3 method for class `allPerms`. * Code coverage: permute now has a test suite that covers ~87% of the current code base. Version 0.8-4 * Update testthat unit testing to recommended usage. Reported by: Hadley Wickham * Example using vegan data is now made conditional upon that package being available. Reported by: Jari Oksanen Fix suggested by: Uwe Ligges * blocks new in-devel extractor and replacement function `blocks`. These are not currently exported so use at your own risk... * permute-deprecate.Rd was missing an \alias{} Reported by: Kurt Hornik (CRAN) Version 0.8-3 * allPerms: with free permutations *within* plots, `allPerms()` was not returning the indices in the original data but in the permutation indices within plots. Reported by: Joris Meys Version 0.8-2 * allPerms: with free permutations *within* blocks, `allPerms()` was not returning the indices in the original data but in the permutation indices within block. In addition, `allPerms()` was not replicating each row in a within-block permutation matrix for all the rows in the other block within-block permutation matrices. This is now achieved via a new, non-exported utility function `cbindAllPerms()`. Reported by: Joris Meys Version 0.8-1 * setBlocks: get block name before doing anything so that you really get only name instead of its evaluated value. Version 0.8-0 * Released to CRAN * DESCRIPTION: now uses `Authors@R` to populate `Author` and `Maintainer` fields. Finer grained recognition of contributors and R Core Team's copyright. * NEWS: added a `NEWS.Rd` file to document high-level changes to permute. Detailed changes remain in `ChangeLog`, whilst `NEWS.Rd` will summarise the main user-level changes to the package. * allPerms: fix a bug where the blocks of permutations were being recombined in the wrong way, by rows instead of by columns. * numPerms: was ignoring the `constant` setting if free permutations within level of plots. Version 0.7-8 * how, Plots: enforces that `blocks` and `strata` are factors, or can be coerced to a factor via `as.factor()`, if specified. * check: gains a new argument `quietly = FALSE` to suppress messages about updates to the permutation design when they are not needed. * allPerms: no longer allows messages about generating set of permutations to be generated by `check()`. It calls `check()` now with `quietly = TRUE` to achieve this. * shuffleSet: played about a bit with the way the design is printed if you show the matrix of permutations. Version 0.7-7 * shuffleSet: Implemented an idea of Jari's to allow `check()` and `allPerms()` to do their thing and possibly generate the set of all permutations, rather than turn off checking. If that now results in more than `nset` permutations, `shuffleSet` randomly takes `nset` of these. This is a nice suggestion as it avoids the problem that with small numbers of possible permutations, you can randomly draw the same permutation more than once. As I have added this feature, I reverted some earlier changes to the documentation that used the `check = FALSE` in their call to `shuffleSet()`. The `check` argument is retained though, as a way for function writers to skip that part of the permute workflow if desired. The permutation matrix returned is now of class `"permutationMatrix"`. This class has `as.matrix()` and `print()` S3 methods. * allPerms: gains an argument `check`, which defaults to `TRUE`. This is used to turn off checking within `allPerms` if desired. A use-case for this is in `check()`, which might end up caling `allPerms()` to generate the set of all permutations. In that case `allPerms()` used to recheck the design. Now this doesn't happen. `allPerms` also uses the new `set<-` replacement functions rather than `update()` as the latter causes problems when used within functions as it often evaluates the stored call in the wrong environment. * check: following the change to `allPerms` (see above), `check()` no longer results in it calling itself, via `allPerms()`, when generating the set of possible permutations if the check heuristics indicate it should be. Turned on some `message()`s when the user asks for too many permutations (more than the set of possible permutations) and when the set of possible permutations is smaller than the `minperm` value stored in the `"how"` object. The latter notifies the user that the entire set of permutations is being generated. These messages were updated to reduce their length. `check` also uses the new `set<-` replacement functions rather than `update()` as the latter causes problems when used within functions as it often evaluates the stored call in the wrong environment. * Plots, Within: now return a object of class `"Plots"` or `"Within"`, respectively. * get-methods: added a number of a new methods for existing functions to work with `"Within"` and `"Plots"` classes. * set-methods: added a number of a new functions and methods with the common name `setFoo<-.Bar` where `Foo` is the component to be updated, and `Bar` is the class. These are replacement functions only. They are intended to be used within functions, where the user-friendly `update()` will have problems getting the call updated correctly ot evaluating it. * how, Plots, Within: Now work much harder to preserve details of the design (i.e. the names of objects passed for the blocks or plot strata), and also process the matched call so that the user can `update()` it. * fixupCall: a new, unexported function that allows the call objects stored in a `"how"` object to be updated. This is not exported as it is intended only for internal use. Function writers should use the `setFoo<-` functions instead. Ordinary users should use `update()` as long as it is not in a function. * update: new methods for objects of classes `"how"` and `"Plots". Thes are copies of the standard R function `update.default` with some changes. The source files for these two functions preserver the R copyright statement and document modifications made by Gavin L. Simpson. * Depends: permute requires a version of R no earlier than version 2.14.0. Version 0.7-6 * summary.allPerms: Was printing two slightly different subtitles. * More unit tests... Version 0.7-5 * how: the matched call is now returned permitting the use of `update()` to update elements of a stored permutation design object. Suggested by Jari Oksanen. `how` also gains an argument `make` which is the user-level way to control whether all possible permutations are actually created should the heuristics in `check()` decide they should be. The `print` method for class "how" wasn't printing details of mirroring or constant settings for within-plot components. * shuffleSet: was incorrectly recombining individual block-level 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. * Within, Plots: as with `how()`, the matched call is now returned as part of the list object, allowing desirable `update()` behaviour. * allPerms, doAllPerms: now correctly work in presence of blocks, and where there are no plots. `allPerms` now includes the permutation design (its `control` argument) as an attribute, `"control"`, on the returned matrix of permutations. `allPerms` loses arguments `max` and `observed` as these are supposed to be in the control object created by `how()`. `summary.allPerms` (its `print` method, more correctly) now prints the permutation design alongside the set of permutations. * get-methods: new extractor functions `getObserved()` and `getMake()` return the `observed` and `make` components of object created by `how()`. * getComplete: This now only returns the `complete` component of the `"how"` object. Use `getMinperm()` to extract the component no-longer returned by `getComplete()`. * check: function loses arguments `make.all` and `observed` as these are in the control object returned by `how()`. The logic of some of the checks has been tweaked slightly. * Documentation fixes in examples of `allPerms` and `check`. * permuplot: This is horribly broken and I'm not sure if it will ever return. In the meantime, this function now prints a warning message if used and returns nothing, invisibly. The function is no longer exported from the package namespace, and not documented. I'm not convinced that the plot can adequately convery the breadth of designs now possible. Hence I am minded to deprecate this in 0.8-0 when released to CRAN and to make it defunct some thereafter. Version 0.7-4 * Deprecated functions: Completed the deprecation of `permCheck()` and `permControl()`. These functions will be made defunct following the release of version 0.8-0, with a view to complete removal from version 0.9-0 onwards. Version 0.7-3 * Tweak to 0.7-2 API changes: argument `blocks` no longer takes a list from helper function `Blocks()`. It is easier and simpler if this just takes a factor. In essence, `blocks` in synonymous with `strata` from `vegan::permuted.index` and the new change will allow for an easier transition. * get-methods: New extractor functions `getMirror()`, and `getConstant()` which retrieve the mirroring and constant elements of a permutation design. Also added `getRow()`, `getCol()` and `getDim()`, which extract the row and column dimensions of a grid permutation design, or both. In addition, new methods `getNperm()` and `getMaxperm()` return the number of permutations requested and the maximum nuber that should be allowed, respectively. New method `getComplete` extracts details of the complete enumeration features of permute. * numPerms: updated to work with the new API and now handles blocking. Exmaples now pass checks again. * allPerms: updated to the new API. * check: updated to the new API. * how: new function, a copy of `permControl()` and will eventually replace that function. Has a new `print` method. Begun process of *deprecating* `permControl()` and its `print` method. * permControl, how: the `strata.name` component of the returned object is no called `blocks.name`. * Plots: now returns the object name supplied as argument `strata` as component `plots.name`. * TODO: started a TODO list of things I know are broken or needed. Version 0.7-2 * Major API change: Added capability to handle true blocking constraints. Suggested by Cajo ter Braak. We now have: o Blocks: samples are *never* permuted between blocks. Blocks can't be permuted either. o Plots: these define groups of samples, for example the whole plots in a split-plot design, or repeated measures on a set of sites. The sites are the "plots". Plots can be permuted using any of the restricted schemes offered in permute. o Within: these are the samples, the rows in the data set. They can be nested in Plots and/or in Blocks. This capability has made it into permControl(), shuffle() and shuffleSet(), though the latter certainly has one major bug in the case where there is more than one Block. Most other functionality is broken as the above change has altered the permControl object in a way that is not backwards compatible. Note that the 0.7.x branch is a development branch and should not be used in ernest until I work through all the implications of this change. Rest assured, I won't be doing this again! Version 0.7-1 * allPerms: implement Doug Bates version which simplifies and speeds up the code. A fast RcppEigen-based version also exists but will need larger changes to the package to implement. Version 0.7-0 * Vignette: silly typo is example code illustrating shuffle(). New section on `shuffleSet()`. The Vignette is now in `vignettes` not `inst/doc`. * check.Rd: undo the hack needed to pass checks prior to vegan 2.0 being on CRAN. * Suggests: now needs vegan >= 2.0-0 * shuffleGrid: was doing random flipping of permutations even if `mirror = FALSE` for the `constant = TRUE` case. * shuffleStrata: assumed that the samples were in contiguous blocks. Reported by Cajo ter Braak. * .Internal: removed all instances of .Internal calls in the code. * Package is now byte-compiled. Version 0.6-1 (released to CRAN on September 7, 2011) * NAMESPACE: export(permuplot) * check.Rd: temporarily supress some of the examples to run only on vegan >= 2.0-0. Needed during transition to pass checks on CRAN until version 2.0-0 is released. Version 0.6-0 (closed September 7, 2011) * allPerms: added warning regarding current need for samples to be arranged in order of any strata. * Release: Pushed to CRAN. First beta release. Version 0.5-4 (opened August 31, 2011) * permCheck: deprecate `permCheck()` in favour of `check()`. * allPerms: code clean-up * preparing for first release to CRAN. Version 0.5-3 (closed August 31, 2011) * shuffleSet: now handles all permutation types that are available in shuffle(). * nobs.Rd: fixed an example which created a numeric vector of zeros instead of changing sampled vector to numeric. The example yielded an error in R 2.14.0 (under development) where only one argument was accepted for numeric() and two or more args cause an error. The two isTRUE() cases should be true only exceptionally, and may call for a fix. * NAMESPACE, nobs-methods.R: The package relied on import(stats, nobs), but that works only in R 2.13 and failed in R 2.12.2. Now we define and export nobs() generic in permute package for older R. The help file still gives a warning for missing documentation of nobs in R 2.12.2 and prior, but there is no obvious fix to this. Version 0.5-2 (closed August 23, 2011) * shuffelSet: new function to generate a set of `n` permutations without the overhead of `n` repeated calls to `shuffle()`. Currently only for designs without strata/blocks. Version 0.5-1 (closed July 5, 2011) * shuffle: now returns seq_len(n) for no permutation within blocks or of blocks. * tests: testing using the `testthat` package. Initial infrasctructure. Version 0.5-0 (closed June 28, 2011) * shuffle: renamed permuted.index() to shuffle() * Vignette: the package has a vignette, which is very much a work-in-progress. Version 0.0-3 (closed June 17, 2011) * NAMESPACE: permute gets a NAMESPACE. Needed to shield functions form ones of similar name in vegan. Version 0.0-2 (closed December 09, 2010) * allPerms: Large update. allPerms now works for all permutation designs *except* when permuting both blocks and within blocks. This exception is handled with .NotYetImplemented(). * numPerms: Wasn't returning the correct number of permutations when WITHIN == "none" and BLOCK != "none", i.e. permuting strata. * Utils: Utility functions defined inline within allPerms moved to new proper functions and renamed; allFree, allSeries allGrid, allStrata. Version 0.0-1 (closed February 28, 2010) * SVN: Uploaded code to r-forge within vegan source tree. This code base represents my working version as of today, *not* the version in vegan at that time.