generate_design: Generate an efficient experimental design

In spdesign: Designing Stated Preference Experiments

Generate an efficient experimental design

Description

The function generates efficient experimental designs. The function takes a set of indirect utility functions and generates efficient experimental designs assuming that people are maximizing utility.

Usage

generate_design(
  utility,
  rows,
  model = "mnl",
  efficiency_criteria = c("a-error", "c-error", "d-error", "s-error"),
  algorithm = c("federov", "rsc", "random"),
  draws = c("pseudo-random", "mlhs", "standard-halton", "scrambled-halton",
    "standard-sobol", "scrambled-sobol"),
  R = 100,
  dudx = NULL,
  candidate_set = NULL,
  exclusions = NULL,
  save_designs = FALSE,
  control = list(cores = 1, max_iter = 10000, max_relabel = 10000, max_no_improve =
    1e+05, efficiency_threshold = 1e-06, sample_with_replacement = FALSE,
    allow_reversed_pairs = FALSE)
)

Arguments

utility	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.
rows	An integer giving the number of rows in the final design
model	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.
efficiency_criteria	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.
algorithm	A character string giving the optimization algorithm to use. No default is set and the argument must be specified to be one of 'rsc', 'federov' or 'random'.
draws	The type of draws to use with Bayesian priors. No default is set and must be specified even if you are not creating a Bayesian design. Can be one of "pseudo-random", "mlhs", "standard-halton", "scrambled-halton", "standard-sobol","scrambled-sobol".
R	An integer giving the number of draws to use. The default is 100.
dudx	A character string giving the name of the prior in the denominator. Must be specified when optimizing for 'c-error'
candidate_set	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 it is built from the utility functions subject to specified exclusions with build_candidate_set. 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.
exclusions	A list of exclusions Often this list will be pulled directly from the list of options or it is a modified list of exclusions
save_designs	A boolean indicating whether to save up to 10 intermediate designs. The default value is FALSE.
control	A list of control options. Set 'allow_reversed_pairs = TRUE' to include the profiles of exchangeable alternatives in every order when the candidate set is built. See build_candidate_set.

Details

No assumptions are made with respect to default values and it is up to the user to specify optimization criteria, optmization routines, draws to use for Bayesian priors and more.

Value

An object of class 'spdesign'. For the 'federov' algorithm, the list element 'runs' holds the best design of each run of the search and its efficiency criteria. The best design across all runs is the one returned as the design.

spdesign documentation built on Oct. 6, 2026, 9:07 a.m.