design.mad: Generate a modified augmented design layout
In austinjcase/BreedR: An R package for managing a breeding program

Description Usage Arguments Details Value References Examples

View source: R/design.mad_function_vFldTrial.R

design.mad generates a field layout whose various attributed originate from Lin and Poushinsky's modified augmented desing (type 2) (Lin and Poushinsky, 1985), with modifications made by the Barley CAP (http://www.barleycap.org) to accomodate standard row crop field plots (Figure 2). See Details for more information.

design.mad(enviro = format(Sys.Date(), "%x"), exp.name = NULL,
  entries = NULL, nEntries = NULL, chks = NULL, nChk2 = NULL,
  nFieldRows = NULL, nFieldCols = NULL, nChk2.min = 3,
  plot.start = 1001, plot_id.template = NULL, minPerChks = 0.1,
  maxPerChks = 0.5, 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`.
`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`.
`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 modified augmented design (type 2) was originally proposed by Lin and Poushinsky (1985). The design originally arranged experimental entries in a grid pattern consisting of "whole plots" (WPs), with the dimension of each whole plot being 1 row x 5 columns. At the center of each WP was a "control" or check plot denoted as the primary check. Furthermore, a subset of the WPs also contained secondary check lines. See Figure 1 from Lin and Poushinsky (1985) for details on the original (type 2) modified augmented desging. This type of design allowed for multiple adjustment procedures to correct for spatial heterogeneity (i.e. spatially-related error variance) (Lin and Poushinsky, 1985). Because of its heavy use of check plots (20 percent guaranteed from primary checks alone!) the traditional type 2 MAD was modified by the Barley CAP (http://www.barleycap.org). The dimesion of the WPs have been changed to 3 rows x 5 columns (Figure 2), and the center plot is still retained as the "control" or check plot. Secondary checks (typically 2-3) are still assigned to a subset of the blocks. The advantage of this modification is that fewer check plots are required, however it places a stronger restriction on overall field size, specifically that the field dimensions must be reducible by the 3 row x 5 column WP sizes. The adjustment procedures for correcting spatially-related error from Lin and Poushinsky (1985) are retained and described in more depth in the documentation for the function adjust.fld.

Figure 1: Lin.Pulinsky_mad_Fig1.jpg

Figure 2:

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

mad.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
mad.ex1 <- design.mad(exp.name = "ex1", nEntries = 250,
             nChk2 = 2, nFieldRows = 9)

## Example 2 - Provide entries and checks
               Provide both nFieldRows and nFieldCols
mad.ex2 <- design.mad(exp.name = "ex2",
             entries = paste("Line", 1:300, sep = "."),
             chks = c("Larry", "Curly", "Moe"),
             nFieldRows = 12, nFieldCols = 30)

## End(Not run)