dae (version 3.0-32)

designRandomize: Randomize allocated to recipient factors to produce a layout for an experiment

Description

A systematic design is specified by a set of allocated factors that have been assigned to a set of recipient factors. In textbook designs the allocated factors are the treatment factors and the recipient factors are the factors indexing the units. To obtain a randomized layout for a systematic design it is necessary to provide (i) the systematic arrangement of the allocated factors, (ii) a list of the recipient factors or a data.frame with their values, and (iii) the nesting of the recipient factors for the design being randomized. Given this information, the allocated factors will be randomized to the recipient factors, taking into account the nesting between the recipient factors for the design. However, allocated factors that have different values associated with those recipient factors that are in the except vector will remain unchanged from the systematic design.

Also, if allocated is NULL then a random permutation of the recipient factors is produced that is consistent with their nesting as specified by nested.recipients.

For examples of its use also see the vignette daeDesignNotes.pdf.

Usage

designRandomize(allocated = NULL, recipient, nested.recipients = NULL, 
                except = NULL, seed = NULL, unit.permutation = FALSE, ...)

Arguments

allocated

A factor or a data.frame containing the systematically allocated values of the factor(s). If NULL, a random permutation of the recipient factors is produced that is consistent with their nesting as specified by nested.recipients.

recipient

A data.frame or a list of factors, along with their levels that specify the set of recipient factors that are allocated levels of the allocated factors.

If a list, the name of each component of the list is a factor name and the component is either (i) a single numeric value that is the number of levels, (ii) a numeric vector that contains the levels of the factor, (iii) or a character vector that contains the labels of the levels of the factor. The values of factors will be generated in standard order using fac.gen and so the values in allocated must match this.

nested.recipients

A list of the recipient factors that are nested in other factors in recipient. The name of each component is the name of a factor that is nested and the component is a character vector containing the factors within which it is nested. It is emphasized that the nesting is a property of the design that is being employed (it is only partly based on the intrinsic nesting).

except

A character vector containing the names recipient factors that are to be excepted from the permutation; any allocated factors whose values differ between the levels of the factors in this vector will not have those values randomized.

seed

A single numeric value, interpreted as an integer, that specifies the starting value of the random number generator.

unit.permutation

A logical indicating whether to include the .Unit and .Permutation columns in the data.frame.

...

Further arguments passed to or from other methods. Unused at present.

Value

A data.frame with the values for the recipient and allocated factors that specify the layout for the experiment and, if unit.permutation is TRUE, the values for .Units and .Permutation vectors.

Details

A systematic design is specified by the matching of the supplied allocated and recipient factors. If recipient is a list then fac.gen is used to generate a data.frame with the combinations of the levels of the recipient factors in standard order. Although, the data.frames are not combined at this stage, the systematic design is the combination, by columns, of the values of the allocated factors with the values of recipient factors in the recipient data.frame.

The method of randomization described by Bailey (1981) is used to randomize the allocated factors to the recipient factors. That is, a permutation of the recipient factors is obtained that respects the nesting for the design, but does not permute any of the factors in the except vector. This permutation is applied to the recipient factors. Then the data.frame containing the permuted recipient factors and that containng the unpermuted allocated factors are combined columnwise, as in cbind. To produce the randomized layout, the rows of the combined data.frame are reordered so that its recipient factors are in either standard order or, if a data.frame was suppled to recipient, the same order as for the supplied data.frame.

The .Units and .Permutation vectors enable one to swap between this permutation and the randomized layout. The ith value in .Permutation gives the unit to which unit i was assigned in the randomization.

References

Bailey, R.A. (1981) A unified approach to design of experiments. Journal of the Royal Statistical Society, Series A, 144, 214--223.

See Also

fac.gen, designLatinSqrSys, designPlot, designAnatomy in package dae.

Examples

# NOT RUN {
## generate a randomized layout for a 4 x 4 Latin square
## (the nested.recipients agument is not needed here as none of the 
## factors are nested)
LS.unit <- data.frame(row = ordered(rep(c("I","II","III","IV"), times=4)), 
                      col = factor(rep(c(0,2,4,6), each=4)))
LS.trt <- data.frame(treat = factor(designLatinSqrSys(4), label = LETTERS[1:4]))
data.frame(LS.unit, LS.trt)
LS.lay <- designRandomize(allocated = LS.trt, recipient = LS.unit, 
                          seed = 7197132, unit.permutation = TRUE) 
LS.lay[LS.lay$.Permutation,]

## generate a randomized layout for a replicated randomized complete 
## block design, with the block factors arranged in standard order for 
## rep then plot and then block
RCBD.unit <- list(rep = 2, plot=1:3, block = c("I","II"))
## specify that plot is nested in block and rep and that block is nested
## in rep
RCBD.nest <- list(plot = c("block","rep"), block="rep")
## generate treatment factor in systematic order so that its values correspond
## to plot
tr <- factor(rep(1:3, each=2, times=2))
## obtain randomized layout
RCBD.lay <- designRandomize(allocated = tr, 
                            recipient = RCBD.unit, 
                            nested.recipients = RCBD.nest, 
                            seed = 9719532, 
                            unit.permutation = TRUE)
#sort into the original standard order
RCBD.perm <- RCBD.lay[RCBD.lay$.Permutation,]
#resort into randomized order
RCBD.lay <- RCBD.perm[order(RCBD.perm$.Units),]

## generate a layout for a split-unit experiment in which: 
## - the main-unit factor is A with 4 levels arranged in 
##   a randomized complete block design with 2 blocks;
## - the split-unit factor is B with 3 levels.
SPL.lay <- designRandomize(allocated = fac.gen(list(A = 4, B = 3), times = 2), 
                           recipient = list(block = 2, main.unit = 4, split.unit = 3), 
                           nested.recipients = list(main.unit = "block", 
                                                    split.unit = c("block", "main.unit")), 
                           seed=155251978)

## Generate a permutation of Seedlings within Species
seed.permute <- designRandomize(recipient = list(Species = 3, Seedlings = 4),
                                nested.recipients = list(Seedlings = "Species"),
                                seed = 75724, except = "Species", 
                                unit.permutation = TRUE)
# }