dae (version 3.2.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 accessed via vignette("DesignNotes", package="dae") and for a discussion of its use see Brien, Sermarini and Demetro (2023).

Usage

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

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.

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. The randomization is controlled by nested.recipients: nested recipient factors are permuted within those factors that nest them. Only the nesting is specified: it is assumed that if two factors are not nested then they must be crossed. It is emphasized that the nesting is a property of the design that is being employed (it is only partly based on the intrinsic or physical crossing and nesting).

except

A character vector containing the names of 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.

Author

Chris Brien

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. A permutation is generated for all combinations of the recipient factors, except that a nested factor, specifed using the nested.recipients argument, cannot occur in a combination without its nesting factor(s). These permutations are combined into a single, units permutation that 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 combined, units 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

## Generate a randomized layout for a 4 x 4 Latin square
## (the nested.recipients argument is not needed here as none of the 
## factors are nested)
## Firstly, generate a systematic layout
LS.sys <- cbind(fac.gen(list(row = c("I","II","III","IV"), 
                             col = c(0,2,4,6))),
                treat = factor(designLatinSqrSys(4), label = LETTERS[1:4]))
## obtain randomized layout
LS.lay <- designRandomize(allocated = LS.sys["treat"], 
                          recipient = LS.sys[c("row","col")], 
                          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
## Firstly, generate a systematic order such that levels of the 
## treatment factor coincide with plot
RCBD.sys <- cbind(fac.gen(list(rep = 2, plot=1:3, block = c("I","II"))),
                  tr = factor(rep(1:3, each=2, times=2)))
## obtain randomized layout
RCBD.lay <- designRandomize(allocated = RCBD.sys["tr"], 
                            recipient = RCBD.sys[c("rep", "block", "plot")], 
                            nested.recipients = list(plot = c("block","rep"), 
                                                     block="rep"), 
                            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.
## Firstly, generate a systematic layout
SPL.sys <- cbind(fac.gen(list(block = 2, main.unit = 4, split.unit = 3)),
                 fac.gen(list(A = 4, B = 3), times = 2))
## obtain randomized layout
SPL.lay <- designRandomize(allocated = SPL.sys[c("A","B")], 
                           recipient = SPL.sys[c("block", "main.unit", "split.unit")], 
                           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)