design.rcbd: Generate a randomized complete block design
In austinjcase/BreedR: An R package for managing a breeding program

Description Usage Arguments Details References Examples

View source: R/design.rcbd_function_vFldTrial.R

Randomized complete block designs (RCBD) are exceedingly common experimental designs in many field, including agricultural reserach. Details on RCBDs can easily be found in basic experimental design textbooks or an internet search; briefly, a set of experimental entries along with check lines, if desired, comprise a single block. This block is then replicated in its entirety at least once (i.e. two blocks) and up to any number of times.

design.rcbd(enviro = format(Sys.Date(), "%x"), exp.name = NULL,
  nBlks = 2, entries = NULL, nEntries = NULL, chks = NULL, nChks = 0,
  nChkReps = 1, nFieldRows = NULL, nFieldCols = NULL, plot.start = 1001,
  fillWithEntry = T, fillWithChk = F, dup.list = NULL,
  plot_id.template = NULL)

`enviro`	Optional `character string` describing the environment which the field trial will be grown in. Default is the current date and time.
`exp.name`	Required `character string` identifying name for the experiment.
`nBlks`	Optional `Integer` indicating the number of complete blocks desired. Default is `2`. If a single replication is desired to grow across multiple environments (aka locations, see `Details` for further information) then set nBlks to `1`.
`entries`	A `character vector` of experimental (i.e. not check) entries. User must either provide this OR `nEntries` (see next).
`nEntries`	`Integer` argument indicating how many experimental entries are to be included in the trial. If `nEntries` = m, then m generic entry names will be generated and included in the output. User must either provide this OR `entries`.. `nEntries` will be superceded if `entries` is provided.
`chks`	A `character vector` including the set of check lines to be included. User must either provide this OR `nChks` (see next).
`nChks`	`Integer` argument indicating how many check lines (see `Details`) are to be included in the trial. DUser must either provide this OR `chks`.
`nChkReps`	Optional `Integer` argument indicating how many times each check line should be replicated per block. Default is `1` meaning that each check line will appear in each block twice (i.e. replicated once).
`nFieldRows`	Optional, but must be provided if nFieldCols is not. `Integer` argument indicating the number of field rows (dimension 'a' in Figure 1).This value can be calculated internally by passing only `nFieldCols`.
`nFieldCols`	Optional, but must be provided if nFieldRows is not `integer` argument indicating the number of field columns (dimension 'b',Figure 1). This value can be calculated internally by passing only `nFieldRows`.
`plot.start`	Optional `integer` indicating the identification number of the first plot. `design.aibd` places the first plot in the "bottom-left" corner of the field and numbering then serpentines, starting to the right (Figure 1). Default is `1001`.
`fillWithEntry`	Optional `Logical`. Default is `TRUE`, meaning fill plots (i.e. plots remaining after the defined sets of experimental entries and check lines are assigned) will be replaced by randomly-selected experimental entries. A "D" will appear in the output next to these replicated entries.
`fillWithChk`	Optional `Logical`. If `TRUE` this will supercede `fillWithEntry` and any fill plots will be replaced by a balanced set of check lines. Default is `FALSE`.
`dup.list`	Optional `character vector` containing the candidates that could be replicated if `fillWithEntry = TRUE`. This is useful if there is a low amount of source seed for some experimental entries; those, for example, would be excluded from `dup.list`. Default is `NULL`, meaning that all entries are candidates for duplication.
`plot_id.template`	Optional `character vector` of length two. The first character is a string that will preceed the plot number in the plot_id field of the output, and the second character is the character to delimit the provided string and the plot number. For example, c("EnvA_TrialA", "_") will result in "EnvA_TrialA_1001", etc.

Figure 1 presents a simplified version of an RCBD with two replications within an environment where each block is a rectangle and there are no fill plots. In reality a block may end and the next start in the middle of a row; this is done to minimize the size of the experiment while meeting all requirements.

RCBD may not be well-suited for all circumstances; in these cases consider using other design functions included in FldTrial: design.aibd or design.mad.

@return A list containing:

rcbd.dgn A dataframe of the resulting design. A line code of 0 denotes an experimental entry, codes of 1, 2, ..., (nChks) denote the first, second, up to the (nChks)-th check, respectively. The order of the check lines and thus line code is arbitrary and has no bearing on placement or randomization. If fillWithEntry is TRUE then a "D" will be placed in the "Duplicates" column for all duplicated entries. Note that the column name "replication" is used in rcbd.dgn rather than "block" or "blk" for reasons related to compatibility with a preferred data entry software.
plot.layout A matrix of plot numbers reflecting the field layout. The first column contains field row numberis (i.e. 1:nFieldRows) and the last row contains field column numbers (i.e. 1:nFieldCols). See Figure 1.
check.layout A matrix of line codes reflecting the field layout. See plot.layout for further details.
rep.layout A matirx of block assignments reflecting the field layout. See plot.layout for further details.
field.dim The dimensions of the resulting field design; nFieldRows x nFieldCols, or a x b (Figure 1).
nDuplicates The number of duplicated experimental entries. Will only be non-zero if fillWithEntry is TRUE.
rlzPerChks The final percentage of the designed represented by check lines. This can be affected by nChkReps and fillWithCheck

Bernardo, Rex. 2010. Breeding for Quantitative Traits in Plants. Stemma Press. Woodbury, MN.

## Not run: 
## Example 1 - Generic layout with 2 reps
rcbd.ex1 <- design.rcbd(exp.name = "ex1", nBlks = 2,
               nEntries = 80, nChks = 3, nChkReps = 3,
               nFieldRows = 8)

## Example 2 - Layout with defined lines and checks
rcbd.ex2 <- design.rcbd(exp.name = "ex2", nBlks = 2,
               entries = paste("Line", 1:75, sep="."),
               chks = c("Larry", "Curly", "Moe"),
               nChkReps = 4, nFieldCols = 20)

## End(Not run)