Skip to content

Generate the sparse or p-rep allocation to multiple locations.

Source: R/fct_do_optim.R

Generate the sparse or p-rep allocation to multiple locations.

Usage

do_optim(
  design = "sparse",
  lines,
  l,
  copies_per_entry,
  add_checks = FALSE,
  checks = NULL,
  rep_checks = NULL,
  force_balance = TRUE,
  seed,
  data = NULL
)

Arguments

design
Type of experimental design. It can be prep or sparse

lines
Number of genotypes, experimental lines or treatments.

l
Number of locations or sites. By default l = 1.

copies_per_entry
Number of copies per plant. When design is sparse then copies_per_entry should be less than l

add_checks
Option to add checks. Optional if design = "prep"

checks
Number of genotypes checks.

rep_checks
Replication for each check.

force_balance
Get balanced unbalanced locations. By default force_balance = TRUE.

seed
(optional) Real number that specifies the starting seed to obtain reproducible designs.

data
(optional) Data frame with 2 columns: ENTRY | NAME. ENTRY must be numeric.

Value

A list with five elements, classed c("fieldhub_sparse_optimization", "Sparse") or c("fieldhub_multi_prep_optimization", "MultiPrep"): the legacy Sparse/MultiPrep class is retained for compatibility, with an additional fieldhub_* class alongside it.

  • multi_location_data is a data frame with the entries of every location: LOCATION | ENTRY | NAME, with a REPS column for p-rep allocations.

  • list_locs is a list with each location list of entries.

  • allocation is a data frame of test-entry copy counts, with one column per location.

  • size_locations is a named vector of test-entry copies per location, excluding checks.

  • metadata records the allocation type, schema version, seed, random-number settings, package version and evaluated input parameters. With the same package versions and RNG settings, rebuild the allocation with do.call(do_optim, x$metadata$parameters). Its allocation_search element records how the search ended: stop_reason, evaluations and even_repairs.

Details

The entry copies are allocated to the locations by FielDHub's own compiled block-design search: D-optimal plot swaps after Edmondson (2020), 20 searches from random starts drawn with the seed (the first starts from a square lattice when the shape is one). Every allocation is even: each entry has floor(copies_per_entry / l) or one more copies at each location (a final even-up step guarantees it), and location totals differ by at most one copy before force_balance. One location takes every copy without a search. From FielDHub 1.7.0 this search replaces blocksdesign::blocks(), so allocations for a given seed differ from earlier versions.

The swap search stops after at most 60 seconds; the even-up step and the final scoring run after it, outside that limit. A run stopped by the limit warns, records stop_reason = "time_limit", and may not be reproducible from its seed, because where it stopped depends on the machine's speed.

References

Edmondson, R.N. Multi-level Block Designs for Comparative Experiments. JABES 25, 500–522 (2020). https://doi.org/10.1007/s13253-020-00416-0

Author

Didier Murillo [aut], Salvador Gezan [aut], Ana Heilman [ctb]

Examples

sparse_example <- do_optim(
   design = "sparse",
   lines = 120,
   l = 4,
   copies_per_entry = 3,
   add_checks = TRUE,
   checks = 4,
   seed = 15
)