designRandomize: Randomize allocated to recipient factors to produce a layout...
In dae: Functions Useful in the Design and ANOVA of Experiments

designRandomize

R Documentation

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, ...)

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.

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.

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.

Author(s)

Chris Brien

References

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

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)

dae documentation built on Aug. 21, 2025, 5:56 p.m.