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.

