designRandomize {dae} | 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 |

`recipient` |
A If a |

`nested.recipients` |
A |

`except` |
A |

`seed` |
A single |

`unit.permutation` |
A |

`...` |
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 *i*th 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.

### 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)
```

*dae*version 3.2.28 Index]