counterbalance: Get a set of minimially replicated sequences
In drknexus/repsych: Package for reproducible psychological research

Description Usage Arguments Value Details Warning Author(s) Examples

This function (attempts to) provide a maximally counterbalanced set of sequences from the full possible set of sequences.

1 2	counterbalance(conds, N, toomany = 2, iter = 500, pb = TRUE, latinSquareFunction = latinSquareDigram)

`conds`	(vector) A of condition IDs or condition names
`N`	(numeric) The number of sequences desired
`toomany`	(numeric) If there are this many (or more) extra occurances of a given condition at a given order position by the time the function returns, then a warning is generated.
`iter`	(integer) The maximum number of iterations to search for a set of permutations that does not fail the `toomany` criterion. If you don't want a search to take place, set iter to -1. Note that if iter is == -1, then pb == FALSE by default. The default value of 500 seems sufficicent for at least 95% of common cases
`pb`	(boolean) Indicate whether you want a progress bar. Having a progress bar may make solution finding slower.
`latinSquareFunction`	(function) The function you want to use to produce latin squares. The arguments and returns for such a function should be like `latinSquareDigram`.

N x conds (matrix) of sequences (by rows)

When the number of requested sequences allows for a (multiple) set(s) of full permtations (a.k.a. t x t! design or full rectangular array) to be used, it is provided.

If the number of sequences requested does not allow for a(nother) full set of permutations, then the remaining sequences are selected from full digram balanced latin squares. The assignment of conditions to values in those latin squares are randomized between squares with the constraint that no two squares can use the same set of assignments. In addition, if iter is greater than 0, an attempt is made to meet the constraint that no condition is assigned to any given value in the latin square toomany (or more) times more than any other.

If the number of sequences requested does not allow for a(nother) full (set of) digram balanced latin square(s), the remaining requested sequences are randomly selected from a latin square with an as yet used assignment of condtions to values selected according to the constraints used in the selection of full latin squares. In addition, if iter is greater than 0, an attempt is made to meet the constraint that no condition is assigned to any position toomany (or more) times more than any other. A warning message is generated if this constraint is not met before the limit set in iter is reached.

The function will not work for large numbers of conditions because the ability to fit all possible permutations into memory is compromised!

Russell S. Pierce Russell.S.Pierce@gmail.com

#counterbalance(LETTERS[1:4],12) #not run, time consuming
counterbalance(LETTERS[1:4],25)

#Sample code to check the maximum difference in the number of times a condition appears in a given position
checkmaxdiff <- function(mat) {
 mat.levels <- as.character(sort(unique(as.vector(mat))))
 mat.factor <- as.data.frame(apply(mat,2,as.character))
 mat.factor <- lapply(mat.factor,factor,levels=mat.levels)  
 return(max(unlist(lapply(lapply(lapply(mat.factor,table),range),diff))))
}

## Example code not run
#Checking number of iter required
#combinations <- expand.grid(Ncond=3:10,N=1:300)
#combinations$howmany <- NA
#for (i in 1:nrow(combinations)){
# res <- counterbalance(1:combinations[i,"Ncond"],combinations[i,"N"],toomany=1,iter=1000)
# combinations[i,"howmany"] <- checkmaxdiff(res)
#}