The modified Federov algorithm implemented here starts with a random design candidate and systematically swaps out rows of the design candidate to iteratively find better designs. It is a first-improvement variant: a swap is kept as soon as it improves the design, instead of searching the entire candidate set for the best swap. A swap that does not improve the design is discarded. The algorithm has the following steps and restrictions.
federov(
design_object,
model,
efficiency_criteria,
utility,
prior_values,
dudx,
candidate_set,
rows,
save_designs,
control
)A list of class 'spdesign' created within the
generate_design function
A character string indicating the model to optimize the design for. Currently the only model programmed is the 'mnl' model and this is also set as the default.
A character string giving the efficiency criteria to optimize for. One of 'a-error', 'c-error', 'd-error' or 's-error'. No default is set and argument must be specified. Optimizing for multiple criteria is not yet implemented and will result in an error.
A named list of utility functions. See the examples and the vignette for examples of how to define these correctly for different types of experimental designs.
A list of priors
A character string giving the name of the prior in the denominator. Must be specified when optimizing for 'c-error'
A matrix or data frame in the "wide" format containing all permitted combinations of attributes. The default is NULL. If no candidate set is provided, then the full factorial subject to specified exclusions will be used. This is passed in as an object and not a character string. The candidate set will be expanded to include zero columns to consider alternative specific attributes.
An integer giving the number of rows in the final design
A boolean indicating whether to save up to 10 intermediate designs. The default value is FALSE.
A list of control options
A list of class 'spdesign'
1) Create a random initial design and evaluate it. If level occurrences are specified, the initial design satisfies them. 2) Swap the first row of the design candidate with the first row of the candidate set. 3) If no better candidate is found, try the next row of the candidate set. Keep trying new rows of the candidate set until an improvement is found. NOTE: A swap is skipped without being evaluated if it would include the same row multiple times or violate the level occurrences. 4) If a better candidate is found, then we try to swap out the next row in the design candidate, continuing with the next row of the candidate set. If no row of the candidate set improves the current row of the design candidate, move on to the next row. 5) When the end of the design candidate or the candidate set is reached, continue from the first row. This way every row of the candidate set is tried equally often. 6) If a full pass over all rows of the design candidate and the candidate set finds no improvement, the design candidate is a local optimum. Store it and restart from step 1 with a new random design candidate. 7) The algorithm terminates after a pre-determined number of iterations or when a pre-determined efficiency threshold has been found. Pressing Esc (or Ctrl + C) stops the search and returns the best design found so far.
The best design found across all runs is returned as the design. The best design of each run, including the one that is still running when the search stops, is stored in the list element 'runs' together with its efficiency criteria.
For very large candidate sets, the maximum number of iterations decides how deep into the candidate set the search goes. Every swap moves one row further through the candidate set, but only evaluated swaps count towards the maximum number of iterations. A search that stops after fewer iterations than there are rows in the candidate set may not have tried all of them.
NOTE: I have not yet implemented a duplicate check! That is, I do not check whether the "same" choice rows are included but with the order of alternatives swapped. This can be achieved by further restricting the candidate set prior to searching for designs. That said, "identical" choice rows will not provide much additional information and should be excluded by default in the search process.