design.aibd: Generate a flexible incomplete block design augmented with a...
In austinjcase/BreedR: An R package for managing a breeding program

Description Usage Arguments Details Value References Examples

View source: R/design.aibd_function_vFldTrial.R

design.aibd assists in generating the layout and randomization of an augmented incomplete block design (AIBD) that is first described herein. This design is proposed as a less-restrictive version of the traditional modified augmented design (type 2) (Lin and Poushinsky, 1985) and its more recent revision by the Barley CAP (http://www.barleycap.org); see design.mad for more information. Additionally, it is amendable to a braoder array of spatially-related error reduction procedures (see adjust.fld for more details on such procedures). 'Flexible' refers to the fact that the incomplete blocks within an AIBD are not restricted to a certain size, as in th 3 row x 5 column restriction of the Barley CAP's MAD design (see design.mad, Figure 2). The placement of checks is also less restricted and more random when compared to the prior MAD layouts.

design.aibd(enviro = format(Sys.Date(), "%x"), exp.name = NULL,
  entries = NULL, nEntries = NULL, chks = NULL, nChk2 = NULL,
  nFieldRows = NULL, nRowsPerBlk = NULL, nFieldCols = NULL,
  nColsPerBlk = NULL, nBlks.min = 1, minDims = c(1, 1), maxDims = c(Inf,
  Inf), nChk2.min = 1, plot.start = 1001, plot_id.template = NULL,
  minPerChks = 0, maxPerChks = 0.99, fillWithEntry = T, dup.list = NULL,
  fillWithChk = F)

`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.
`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. The first check included in the list will be assigned as the `primary` check and the remaining will be assigned as `secondary` checks (see `Details`). User must either provide this OR `nChk2` (see next).
`nChk2`	`Integer` argument indicating how many secondary check lines (see `Details`) are to be included in the trial. A primary check is automatically assigned in addition the the `nChk2` secondary checks, brining the total number of unique check lines to nChk2 + 1. User must either provide this OR `chks`.
`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`.
`nRowsPerBlk`	Optional `integer` argument indicating the number of rows per row_blk (dimension 'b', Figure 1). If an argument is provided it must be a divisor if `nFieldRows` to allow for blocking. If an 'optimized' dimension (see `Details`) is desired, leave empty.
`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`.
`nColsPerBlk`	Optional `integer` argument indicating the number of columns per col_blk (dimension 'd', Figure 1). If an argument is provided it must be a divisor if `nFieldCols` to allow for blocking. If an 'optimized' dimension (see `Details`) is desired, leave empty.
`nBlks.min`	Optional `integer` argument indicating the minimum number of incomplete blocks acceptable in the final design. This also controls the minimum number of primary checks since there is one primary check per incomplete block. Default is `3`.
`minDims`	Optional `numeric vector` argument of length 2 indicating the minimum row_blk dimension ('b', Figure 1) and minimum col_blk dimension ('d', Figure 1). Since the experimenter (i.e. user) ultimately knows what is ideal for their field, this is useful for fine-tuning 'optimized' designs. Default is `c(2,4)`, denoting minimum dimension of 2 rows per row_blk and 4 columns per col_blk, respectively.
`maxDims`	Optional `numeric vector` argument of length 2 indicating the maximum row_blk dimension ('b', Figure 1) and maximum col_blk dimension ('d', Figure 1). Default is `c(Inf,Inf)`, denoting that there are no restrictions on block dimensions.
`nChk2.min`	Optional `integer` indicating the number of times each secondary check should appear in the design, i.e. the number of replicates per secondary check. Default is `3`.
`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`.
`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.
`minPerChks`	Optional `numeric` argument in the range [0,1) indicating the minimum acceptable value of percent checks, i.e. what percent of the experiment is represented by a check line? Traditionally, the standard has been 10%. Default is `0.09`.
`maxPerChks`	Optional `numeric` argument in the range (0,1] indicating the maximum acceptable value of percent checks. If this value is exceeded during the creation of the field design the function will return a `warning` indicatin such. Default is `0.25`.
`fillWithEntry`	Optional `logical`. Default is `TRUE`, meaning `FILL` plots remaining after `minPerCheck` has been reached will be replaced by randomly selected experimental entries. A "D" will appear in the output next to these replicated entries.
`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.
`fillWithChk`	Optional `logical`. If `TRUE` this will supercede `fillWithEntry` and any `FILL` plots remaining after `minPerCheck` has been reached will be replaced by secondary check lines. Default is `FALSE`.

The main highlights of AIBD and design.aibd:

Adjustments based on blocking factors, e.g. block (b*d, Figure 1), row blocks (b, Figure 1), column blocks (d, Figure 1), can be implemented since:
- A primary check appears once, at random, in each incomplete block. This facilitates the use of downstream adjustment procedures that address spatially-related environmental variance.
- A set of secondary checks are distributed throughout the experiment in a nearly-random process. This refers to the fact that as the sampling process has been tailored to ensure fairly even distribution of checks across blocks, hoewever placement within blocks is completely at random. All adjustment procedures are carried out by the function adjust.fld.
Since field researchers typically know the depth of the experimental site and their plot dimensions users are required to provide, at a minimum, the number of field rows (Figure 1, dimension a), i.e. nFieldRows. Additional field dimensions can also be provided if desired as long as they allow all design requirements to be fulfilled. The following outline the various scenarios of user field dimension (refer to Figure 1) input:
- Scenario 1: All field dimensions (a, b, c, d, respectively) are provided
- Scenario 2: nFieldRows and nRowsPerBlk (a and b), OR nFieldCols and nColsPerBlk (c and d) are provided
- Scenario 3: nFieldRows and nFieldCols (a and c) are provided
- Scenario 4: Most naive scenario - only nFieldRows (a) OR nFieldCols is provided
In each of the above scenarios, the field dimension not provided will be determined by design.aibd; minPerChks is used as the starting point to determine the remainder of the field dimensions. Ultimately, the goal of design.aibd is to provide an 'optimized' design that meets the users requirements while remaining as close to the minPerChk argument as possible.
The nature of the 'optimization' procedure mentioned just above can result in field designs that meet all requirements but posses some undesireable characteristic(s) to the user. Some common issues and their solution are listed below:
- Block dimensions or number of blocks is not desireable: Define minBlkDims and/or maxBlkDims to modulate nRowsPerBlk (b), nColsPerBlk (d), and the number of blocks. Since each block contains a primary check, this can also be used to control the number of primary checks replicates.
- More checks are desired than what are initially assigned, but the user does not want to increase the overall experiment size: Set fillWithCheck to TRUE, which will result in fill plots to be replaced with secondary check lines rather than replicated experimental entries.

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

A list containing:

aibd.dgn A dataframe of the resulting design. A line code of 0 denotes an experimental entry, codes of 1, 2, ..., (nChk2 + 1) denote the primary, first secondary, up to the (nChk2 + 1)-th secondary check, respectively. 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 to denote whole block replication, whereas "blk" denotes plot assignments to incomplete blocks.
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).
check.layout A matrix of line codes reflecting the field layout. See plot.layout for further details.
blk.layout A matirx of block assignments reflecting the field layout. See plot.layout for further details.
field.dims The dimensions of the resulting field design; nFieldRows x nFieldCols, or a x c (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 may be different than minPerChks, especially when fillWithCheck is TRUE.

Lin, C.-S. and G. Poushinsky. 1985. A modified augmented design (type 2) for rectangular plots. Can. J. Plant Sci. 65:743-749.

## Not run: 
## Example 1 - Provide only nFieldRows
aibd.ex1 <- design.aibd(exp.name = "ex1", nEntries = 350,
             nChk2 = 3, nFieldRows = 10)

## Example 2 - Provide nRowsPerBlk as well
aibd.ex2 <- design.aibd(exp.name = "ex2", nEntries = 350,
             nChk2 = 3, nFieldRows = 10, nRowsPerBlk = 5)

## Example 3 - Use minDims to define min nColsPerBlk
aibd.ex3 <- design.aibd(exp.name = "ex3", nEntries = 280,
             nChk2 = 3, nFieldRows = 9, minDims = c(Inf, 10))


## End(Not run)