Package {spdesign}

spdesign: Designing Stated Preference Experiments

Description

Contemporary software commonly used to design stated preference experiments are expensive and the code is closed source. This is a free software package with an easy to use interface to make flexible stated preference experimental designs using state-of-the-art methods. For an overview of stated choice experimental design theory, see e.g., Rose, J. M. & Bliemer, M. C. J. (2014) in Hess S. & Daly. A. doi:10.4337/9781781003152. The package website can be accessed at https://spdesign.edsandorf.me. We acknowledge funding from the European Union's Horizon 2020 research and innovation program under the Marie Sklodowska-Curie grant INSPiRE (Grant agreement ID: 793163). The package features in Mariel et al. (2025) Environmental Valuation with Discrete Choice Experiments in R. (doi:10.1007/978-3-031-89338-4).

Author(s)

Maintainer: Erlend Dancke Sandorf erlend.dancke.sandorf@nmbu.no

Authors:

• Erlend Dancke Sandorf erlend.dancke.sandorf@nmbu.no

• Danny Campbell danny.campbell@stir.ac.uk

See Also

Useful links:

• https://spdesign.edsandorf.me

• https://github.com/edsandorf/spdesign

Print package startup message

Description

The function is called when the package is loaded through library or require.

Usage

.onAttach(libname, pkgname)

Arguments

Value

Nothing

Align x_j with the priors

Description

Renames the columns of x_j from terms to parameters, so that a generic parameter is a single column even if its attribute has a different name in each alternative. Parameters that do not enter the utility function of an alternative are zero for that alternative. The columns are ordered as the priors, which ensures that the variance-covariance matrix derived by derive_vcov matches the priors.

Usage

align_x_j(x_j, terms, names_priors)

Arguments

Value

The list x_j with one column per prior in the order of the priors

Check whether all priors and attributes have specified levels

Description

Check whether all priors and attributes have specified levels

Usage

all_priors_and_levels_specified(x)

Arguments

Value

A boolean equal to 'TRUE' if all are specified and 'FALSE' if not

Check whether any priors or attributes are specified with a value more than once

Description

Check whether any priors or attributes are specified with a value more than once

Usage

any_duplicates(x)

Arguments

Value

A boolean equal to 'TRUE' if specified more than once.

Match names as whole words

Description

Creates regular expressions that match names as whole words, so that e.g. x1 does not match x10, b_x1 or alt1_x1. Names in the utility functions only contain letters, digits and underscores.

Usage

as_whole_word(name)

Arguments

Value

A character vector of regular expressions

Check whether we can achieve attribute level balance

Description

Check whether we can achieve attribute level balance

Usage

attribute_level_balance(x, rows)

Arguments

Value

A boolean equal to 'TRUE' if attribute level balance can be achieved and 'FALSE' otherwise

Generic for getting the attributes and levels from the utility function

Description

Generic for getting the attributes and levels from the utility function

Usage

attribute_levels(x)

Arguments

Value

A named list of attribute levels

Generic for getting the attribute names

Description

Generic for getting the attribute names

Usage

attribute_names(x)

Arguments

Value

A character vector of attribute names

Block the design

Description

The function will take an object of class 'spdesign' and add a blocking column to the design matrix. The function will use random permutations of the blocking column to find the column that minimizes correlation between the blocking column and the design columns. Specifically the target for the minimization procedure is the mean squared correlation.

Usage

block(x, blocks, target = 5e-04, max_iter = 1e+06)

Arguments

Details

The function uses a random permutation so every time you run the function you will get a slightly different blocking column. You can set a seed prior to calling the function to always return the same blocking vector.

If you pass in a design that already contains a blocking column, then this blocking column will be replaced without warning.

Value

A modified 'spdesign' object where the design is replaced with the same design and a blocking column. In addition a correlation vector, number of iterations and the target value are returned as part of the modified 'spdesign' object.

Build the candidate set

Description

Builds the candidate set one alternative at a time instead of from the full factorial of all alternatives. This uses far less memory and avoids choice tasks that are the same apart from the order of the alternatives.

Usage

build_candidate_set(utility, exclusions = list(), allow_reversed_pairs = FALSE)

Arguments

Details

The profiles of each alternative are the full factorial of its attribute levels. Exclusions that only refer to a single alternative are applied to its profiles before the alternatives are combined. Alternatives are exchangeable if their utility functions and profiles are identical apart from the name of the alternative, e.g. two unlabelled alternatives. By default, each choice task contains a set of different profiles for the exchangeable alternatives only once, and the order of the exchangeable alternatives is randomised in each row to ensure that no alternative systematically gets the same profiles. Labelled alternatives are combined with all profiles of the other alternatives, as in the full factorial. Finally, exclusions that refer to more than one alternative are applied.

Because the order of exchangeable alternatives is random, exclusions across exchangeable alternatives must be specified in both directions, e.g. that alt1 dominates alt2 and that alt2 dominates alt1.

With 'allow_reversed_pairs = TRUE' and no exclusions, the candidate set is the full factorial without choice tasks where exchangeable alternatives have the same profile. To create a candidate set with attribute levels that are different from those in the utility functions, use expand.grid.

Value

A data frame with the candidate set

Examples

utility <- list(
  alt1 = "b_x1[0.1] * x1[1:3] + b_x2[-0.2] * x2[c(0, 1)]",
  alt2 = "b_x1      * x1      + b_x2       * x2"
)

build_candidate_set(utility, exclusions = list("alt1_x1 == 1 & alt1_x2 == 0"))

A-error

Description

Computes the A-error of the design, which is equal to the trace of the variance-covariance matrix over the number of parameters to be estimated

Usage

calculate_a_error(design_vcov)

Arguments

Value

A single error measure

C-error

Description

Seeks to minimize the variance of the ratio of two parameters, for example, willingness-to-pay.

Usage

calculate_c_error(design_vcov, p, dudx, return_all)

Arguments

Value

A vector giving the variance of the ratio for each K-1 parameter or a single number with the sum of the variances used for optimization

D-error

Description

Computes the D-error of the design, which is equal to the K-root of the determinant of the variance-covariance matrix.

Usage

calculate_d_error(design_vcov)

Arguments

Value

A single number

Calculate efficiency

Description

The function is called inside evaluate_design_candidate

Usage

calculate_efficiency(
  prior_values,
  design_env,
  model,
  dudx,
  return_all = FALSE,
  significance = 1.96
)

Arguments

Value

A list with a named vector of efficiency criteria and the variance-covariance matrix

Calculate efficiency criteria

Description

The function is a wrapper around calculate_a_error, calculate_c_error, calculate_d_error and calculate_s_error to provide a unified interface for calling and calculating efficiency criteria.

Usage

calculate_efficiency_criteria(
  design_vcov,
  p,
  dudx,
  return_all = FALSE,
  significance = 1.96,
  type
)

Arguments

Details

The function is mainly used internally to evaluate and report on designs, but is exported to allow the user to use the function to calculate the efficiency criteria of the model once it has been run on their data.

Value

See individual efficiency criteria

References

Bliemer and Rose, 2009, Efficiency and sample size requirements for state choice experiments, Transportation Research Board Annual Meeting, Washington DC Scarpa and Rose, 2008, Designs efficiency for non-market valuation with choice modelling: How to measure it, what to report and why, Australian Journal of Agricultural and Resource Economics, 52(3):253-282 Bliemer and Rose, 2005a, Efficiency and sample size requirements for stated choice experiments, Report ITLS-WP-05-08, Institute for Transport and Logistics Studies, University of Sydney Kessels, R., Goos, P. and Vandebroek, M., 2006, A comparison of criteria to design efficient choice experiments, Journal of Marketing Research, 43(3):409-419

S-error

Description

Calculates a "lower bound" sample size to obtain theoretically significant parameter estimates under the assumption that the priors are correct.

Usage

calculate_s_error(design_vcov, p, return_all, significance)

Arguments

Value

A vector giving the "minimum" sample size for each parameter or a single number with the smallest sample size needed for all parameters to be theoretically significant.

Cleans the utility expression

Description

The function cleans the utility expression by removing extra white spaces, removes brackets and other information to return a clean, easy-to-read expression.

Usage

clean_utility(x)

Arguments

Details

We can also use the side-effect of the function on a list of utility expressions that do not contain brackets to return a an updated utility expression with alternative specific attribute names.

Warning: The function does not check if the utility expression *is* clean, which means that running the function multiple times will result in duplicate alternative names for the attributes. You need to pay particular attention to this fact when using the formula update_utility because this function calls clean_utility.

Value

A cleaned utility function as a list

Generic for extracting the vector of priors

Description

Generic for extracting the vector of priors

Usage

## S3 method for class 'spdesign'
coef(object, ...)

Arguments

Value

A vector of named priors used in the optimization

Combine the profiles of a group of exchangeable alternatives

Description

Combine the profiles of a group of exchangeable alternatives

Usage

combine_profiles(n, k, allow_reversed_pairs)

Arguments

Value

A matrix with one row per combination and one column per alternative, giving the rows of the profiles to combine

Check whether the utility function contains dummy coded variables

Description

We are splitting on all separators first before detecting whether we have dummy coded attributes to allow for people reusing the _dummy name for the attribute.

Usage

contains_dummies(string)

Arguments

Value

A boolean equal to 'TRUE' if the utility function contains dummy coded attributes and 'FALSE' otherwise

Correlation

Description

Calculate the correlation of the design. The function gets the design from the design object before passing it to cor from stats. This is a wrapper around cor.

Usage

cor(x, ...)

Arguments

Details

Note that when your design includes constants, the function will print a warning because the standard deviation of a constant is 0.

Value

A matrix with correlations

Cycling of attribute levels

Description

Cycles the attribute levels to create a new design candidate. "Cycling replaces all attribute levels in each choice situation at the time by replacing the first level with the second level, second level with the third etc. Since this change affects all columns, cycling can only be performed if all attributes have exactly the same sets of feasible levels, (e.g., where all variables are dummy coded)." (p. 253).

Usage

cycle(x)

Arguments

Details

This part of the RSC algorithm is rarely invoked.

Value

A cycled design candidate

References

Hensher, D. A., Rose, J. M. & Greene, W., 2005, Applied Choice Analysis, 2nd ed., Cambridge University Press

Define the profiles of each alternative

Description

Defines the profiles of each alternative as the full factorial of its attribute levels, with the exclusions that only refer to that alternative applied, and finds the groups of exchangeable alternatives. See build_candidate_set.

Usage

define_profiles(utility, exclusions = list())

Arguments

Value

A list with the profiles of each alternative, the groups of exchangeable alternatives and the exclusions across alternatives

Define x_j

Description

Defines x_j, the list of attribute matrices with one matrix per alternative. Each matrix has one column per term in the utility function of that alternative: attributes, expanded dummy-coded attributes and, if requested, interaction terms. The columns are named after the terms and keep the order of model.matrix.

Usage

define_x_j(
  utility,
  design_candidate,
  terms = pair_param_terms(update_utility(utility)),
  interactions = TRUE
)

Arguments

Value

A list of model matrices, one per alternative

Derive the variance covariance matrix of the design

Description

The function is a wrapper around derive_vcov_mnl and derive_vcov_rpl and calculates the variance-covariance matrix of the specified model and design given the priors.

Usage

derive_vcov(design_env, model)

Arguments

Value

The variance covariance matrix. If the Fisher information matrix is singular, then return NULL

Derive the variance covariance matrix for the MNL model

Description

The function takes no arguments and is evaluated in context!

Usage

derive_vcov_mnl()

Value

The variance co-variance matrix

Derive the variance covariance matrix for the RPL model

Description

The function takes no arguments and is evaluated in context!

Usage

derive_vcov_rpl()

Value

The variance co-variance matrix

Expand the sequence of integers

Description

Equation 1 in Bhat (2003)

Usage

digitize(n_dim, primes, count, digit)

Arguments

References

Bhat, C. n_draws., 2003, Simulation Estimation of Mixed Discrete Choice Models Using Randomized and Scrambled Halton Sequences, Transportation Research Part B, 9, pp. 837-855

Find the position of the dummy coded attributes

Description

The function will find the position of the dummy coded attributes in the candidate set (in the case of the Modified Federov or Random algorithms) or the design candidate (in the case of the RSC algorithm). This will let us know which columns to coerce to factors prior to defining x_j.

Usage

dummy_names(x)

Arguments

Value

A boolean vector matching the expanded utility expression

Evaluate the design candidate

Description

The evaluation of the design candidate is independent of the optimization algorithm used.

Usage

evaluate_design_candidate(
  utility,
  design_candidate,
  prior_values,
  design_env,
  model,
  dudx,
  return_all,
  significance
)

Arguments

Value

A named vector with efficiency criteria of the current design candidate. If Bayesian prior_values are used, then it returns the average error.

Exclude rows from the candidate set

Description

Each exclusion is evaluated with the columns of the candidate set as variables, and the rows where it is TRUE are removed.

Usage

exclude(candidate_set, exclusions)

Arguments

Value

A restricted candidate set

Expand the list of attributes and levels to the "wide" format

Description

Expands the attributes and levels to the wide format. The nested list is padded with zeros where alternative specific attributes are present to ensure that we can work with square matrices.

Usage

expand_attribute_levels(x)

Arguments

Value

A named vector

Extract all names

Description

Extracts all parameter and attribute names from the utility function. This is a wrapper around str_extract_all with a specified boundary. The function also calls remove_all_brackets to ensure that if a word is used inside a square bracket, e.g. seq, it is not extracted.

Usage

extract_all_names(string, simplify = FALSE)

Arguments

Details

A name is a word that starts with a letter and is not followed by an opening round bracket. This avoids extracting numbers, e.g. the 2 in I(x1^2), and functions such as the interaction operator I() as attributes.

Value

A list or vector with all names

Extract attribute names

Description

Extracts attribute names. It is a wrapper around extract_all_names and extract_param_names.

Usage

extract_attribute_names(string, simplify = FALSE)

Arguments

Value

A Vector or string wtih attribute names

Extract distributions

Description

This function will locate and extract the the distributions for Bayesian priors and random parameters as specified in the design. The output is used to create the matrix of correct draws for priors and parameters.

Usage

extract_distribution(string, type)

Arguments

Details

IMPORTANT: The function will silently drop duplicates.

Value

A named vector of priors or parameters where the type of distribution is given by a character letter: "normal", "lognormal", "uniform" or "triangular"

Extract the frequency of levels

Description

The function extracts how many times each level of an attribute should occur within the design when attribute level balance is not enforced. Note that it extracts the parentheses AFTER the end of the square brackets. Specifying round brackets without the square brackets are syntactically invalid and therefore we want the code to fail in this case.

Usage

extract_level_occurrence(string, simplify = FALSE)

Arguments

Extracts the named values of the utility function

Description

The function extracts the named values of the supplied utility function.

Usage

extract_named_values(string)

Arguments

Value

A named list of parameter and attribute values. Each list element is named and can contain a single prior, a list with a mean and sd, or a vector with attribute levels

Extract the parameter distribution

Description

Extract the parameter distribution

Usage

extract_param_distribution(string)

Arguments

Extract parameter names

Description

Extracts all words starting with "b_". Leverages the fact that all parameters has to start with "b_".

Usage

extract_param_names(string, simplify = FALSE)

Arguments

Value

A list or vector with the parameter names.

Extract the prior distribution

Description

Extract the prior distribution

Usage

extract_prior_distribution(string)

Arguments

Extract specified

Description

Only extract parameters and attributes with specified priors and levels. This is very useful to test whether parameters or attributes are specified multiple times

Usage

extract_specified(string, simplify = FALSE)

Arguments

Extract unparsed named values of the utilitiy function

Description

If the utility function contains parameters that are dummy coded, the dummy coding is handled here. By expanding the dummy coding prior to parsing we can directly consider Bayesian priors for each level.

Usage

extract_unparsed_values(string)

Arguments

Value

A named list of parameter and attribute values. Each list element is named and contains a numeric value or expression to be parsed

Extract the value argument(s)

Description

Extracts the value argument(s) of the supplied string. The value argument is defined as the characters between [] string.

Usage

extract_values(string, simplify = FALSE)

Arguments

Value

A vector or list with the extracted value arguments

Find a design using a modified Federov algorithm

Description

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.

Usage

federov(
  design_object,
  model,
  efficiency_criteria,
  utility,
  prior_values,
  dudx,
  candidate_set,
  rows,
  save_designs,
  control
)

Arguments

Details

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.

Value

A list of class 'spdesign'

Generate the full factorial

Description

This function is deprecated and will be removed in a future version. Use build_candidate_set to build a candidate set from the utility functions, or expand.grid to create the full factorial of a list of attributes with levels that are different from those in the utility functions.

Usage

full_factorial(attrs)

Arguments

Details

The function is a wrapper around expand.grid and generates the full factorial given the supplied attributes.

Value

A data frame containing the full factorial

Examples

attrs <- list(
  a1 = 1:5,
  a2 = c(0, 1)
)

# Instead of full_factorial(attrs)
expand.grid(attrs)

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

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.

Generates a candidate for the RSC algorithm

Description

Creates a design candidate by assuming attribute level balance. Will work out the minimum level of times an attribute must occur for level balance. If level balance cannot be achieved the function will systematically add level occurrences to get as close as possible to attribute level balance.

Usage

generate_rsc_candidate(utility, rows)

Arguments

Value

A data.frame with rows equal to the number of choice tasks and columns equal to the number of attributes in the 'wide' format

Tests whether the utility expression contains Bayesian priors

Description

This is particularly useful for flow-control

Usage

has_bayesian_prior(string)

Arguments

Value

A boolean equal to 'TRUE' if we have Bayesian priors

Tests whether the utility expression contains random parameters

Description

This is particularly useful for flow-control

Usage

has_random_parameter(string)

Arguments

Value

A boolean equal to 'TRUE' if we have random parameters

Find dummy-coded attributes that are not correctly specified

Description

Dummy-coded attributes must have the levels 1, 2, ..., K, where 1 is the base level, and exactly K - 1 priors, one for each level except the base level. Only the number of levels matters for the design, and using 1, 2, ..., K ensures that the expanded dummy-coded attributes and priors are named and ordered consistently.

Usage

invalid_dummy_coding(x)

Arguments

Value

A character vector with the names of dummy-coded attributes that are not correctly specified. Empty if there are none.

Tests whether a utility function is balanced

Description

Tests whether there is an equal number of opening and closing brackets in the utility functions.

Usage

is_balanced(string, open, close)

Arguments

Value

A boolean equal to 'TRUE' if the utility expression is balanced

Print level balance of your design

Description

Prints a table of level balance for your design. If the design is blocked you will get both level balance per block and overall level balance

Usage

level_balance(design, block = FALSE)

Arguments

Test whether level occurrences are specified in the utility functions

Description

Test whether level occurrences are specified in the utility functions

Usage

level_occurrences_specified(utility)

Arguments

Value

A boolean equal to TRUE if level occurrences are specified and FALSE otherwise

Attribute level occurrence lookup tables

Description

Creates a list of lookup tables for attribute level occurrence.

Usage

lvl_occurrences(utility, rows, level_balance)

Arguments

Value

A list the length of the expanced attribute levels. Each list element is a lookup table where the names of the table is the attribute level and the element the number of times the minimum number of times the level occurs.

Measure how far a design candidate is from the level occurrence constraints

Description

For each attribute level, count how often it occurs in the design candidate and find the distance to the nearest allowed number of occurrences. Levels that do not occur in the design candidate are counted as zero occurrences.

Usage

lvl_violation(
  utility,
  x,
  rows,
  ranges = occurrences(utility, rows),
  lvls = expand_attribute_levels(utility)
)

Arguments

Value

The total distance summed over all attribute levels. A value of 0 means that the design candidate satisfies all level occurrence constraints.

Make random draws

Description

A common interface to creating a variety of random draws used to simulate the log likelihood function

Usage

make_draws(n_ind, n_draws, n_dim, seed, type)

Arguments

Value

A matrix of dimensions n_ind*n_draws x n_dim of standard uniform draws

Examples

n_ind <- 10
n_draws <- 5
n_dim <- 3

draws <- make_draws(n_ind, n_draws, n_dim, seed = 10, "scrambled-sobol")
head(draws)

draws <- make_draws(n_ind, n_draws, n_dim, seed = 10, "scrambled-halton")
head(draws)

Make Modified Latin Hypercube Draws

Description

Make Modified Latin Hypercube Draws

Usage

make_mlhs(n_ind, n_draws, n_dim)

Arguments

References

Hess, S., Train, K. E. & Polak, J. W., 2006, On the use of a Modified Latin Hypercube Sampling (MLHS) method in the estimation of a Mixed Logit Model for vehicle choice, Transportation Research Part B, 40, pp. 147-163

Make pseudo random draws

Description

Wrapper for runif to create a common interface

Usage

make_pseudo_random(n_ind, n_draws, n_dim)

Arguments

Make scrambled Halton draws

Description

A function for creating scrambled Halton draws. The code is a translation of the [GAUSS](http://www.caee.utexas.edu/prof/bhat/FULL_CODES.htm) codes written by Professor Chandra Bhat. Note that the maximum number of dimensions for the scrambled Halton draws is limited to 16. This is because only permutations up to prime 16 are included in the permutation matrix. Extending to more than 16 dimensions can be achieved by including a different permutation matrix.

Usage

make_scrambled_halton(n_ind, n_draws, n_dim)

Arguments

Details

The permutations are based on the Braaten-Weller algorithm.

References

Bhat, C. n_draws., 2003, Simulation Estimation of Mixed Descrete Choice Models Using Randomized and Scrambled Halton Sequences, Transportation Research Part B, 9, pp. 837-855

Make scrambled sobol draws

Description

Wrapper function for sobol() from randtoolbox to create a common interface. Owen + Fazure_Tezuka Scrambling

Usage

make_scrambled_sobol(n_ind, n_draws, n_dim, seed = seed)

Arguments

Wrapper for halton()

Description

Wrapper function for halton() from randtoolbox to create a common interface

Usage

make_standard_halton(n_ind, n_draws, n_dim)

Arguments

Make sobol draws

Description

Wrapper function for sobol() from randtoolbox to create a common interface

Usage

make_standard_sobol(n_ind, n_draws, n_dim, seed = seed)

Arguments

Find minimum level occurrences

Description

Find minimium level occurrences. This is useful to ensure/approximate attribute level balance in designs using the Modified Federov Algorithm or the Random design algorithms.

Usage

min_lvl_occurrence(x, rows)

Arguments

Value

A list of minimum level occurrences for the attribute levels

Find the number of levels

Description

Find the number of levels for each attribute

Usage

nlvls(x)

Arguments

Value

A list with the number of levels for each attribute

Evaluating a distribution

Description

The function returns its arguments as a named list. The function is used inside the utility functions. It is transformed to an expression using parse and evaluated using eval. This ensures that in the case of an RPL with Bayesian priors, recursion is handled automatically. This significantly simplifies translating the utility function to lists of parameters to use when optimizing the designs. It is also less error prone.

Usage

normal(mu, sigma)

normal_p(mu, sigma)

lognormal(mu, sigma)

lognormal_p(mu, sigma)

triangular(mu, sigma)

triangular_p(mu, sigma)

uniform(mu, sigma)

uniform_p(mu, sigma)

Arguments

Value

A list of parameters

Functions

• normal(): The normal distribution

• normal_p(): The normal distribution when applied to a prior

• lognormal(): The log normal distribution

• lognormal_p(): The log-normal distribution when applied to a prior

• triangular(): The triangular distribution

• triangular_p(): The triangular distribution when applied to a prior

• uniform(): The uniform distribution

• uniform_p(): The uniform distribution when applied to a prior

Extract or set attribute level occurrences

Description

This function will set the range of attribute level occurrences equal to to the size of the design. This is equivalent to fully letting go of attribute level balance. Letting go of attribute level balance is the default behavior for the Modified Federov algorithm and the Random algorithm.

Usage

occurrences(x, rows)

Arguments

Details

If restrictions are placed on attribute level occurrence in the utility function, then this function will extract these and add them to the output.

Notice that specifying restrictions in the utility function only matters for the Modified Federov and Random algorithms and will in general result in a less efficient design.

Value

A named list of lists where the outer list is for the attributes and the inner list, the levels of each attribute and the number or range of times they can occur

Pair the terms of the utility functions with their parameters

Description

Splits each updated utility function into its additive terms and pairs each term with its parameter, e.g. "b_x1x2 * I(alt1_x1 * alt1_x2)". The function is used on the output of update_utility, where dummy-coded attributes are already expanded.

Usage

pair_param_terms(x)

Arguments

Value

A list with one named character vector per utility function. The values are the parameter names and the names are the terms, both without whitespace.

Prepare the list of priors

Description

Prepare the list of priors

Usage

prepare_priors(utility, draws, R)

Arguments

Value

A list of priors

A generic function for printing an 'spdesign' object

Description

A generic function for printing an 'spdesign' object

Usage

## S3 method for class 'spdesign'
print(x, ...)

Arguments

Value

No return value. Prints the 'spdesign' object.

Creates a printable version of the efficiency criteria

Description

The function prints a string of efficiency criteria to the console and highlights the color of the considered efficiency criteria. Effectively it is a wrapper around multiple calls to cat.

Usage

print_efficiency_criteria(
  iter,
  values,
  criteria,
  digits = 4,
  padding = 10,
  efficiency_criteria
)

Arguments

Value

A character string.

Prints the initial header for the table of results

Description

The function prints the initial header for the console output and colors in the criteria used for optimization. Effectively, the function makes multiple calls to cat.

Usage

print_initial_header(efficiency_criteria, padding = 10, width = 80)

Arguments

Value

Noting

Prints iteration information

Description

Prints iteration information every time a better design is found. The function wraps around print_initial_header and print_efficiency_criteria. This reduces the number of if-statements and function calls within generate_design in an attempt simplify code maintenance.

Usage

print_iteration_information(
  iter,
  values,
  criteria,
  digits = 4,
  padding = 10,
  width = 80,
  efficiency_criteria
)

Arguments

Value

Nothing

Generic for extracting the vector of priors

Description

Generic for extracting the vector of priors

Usage

priors(x)

Arguments

Value

A list of named priors used in the optimization

Calculate the probabilities of the design

Description

Will take the design object and calculate the probabilities of each alternative and choice tasks.

Usage

probabilities(x)

Arguments

Details

Using Bayesian priors the average across the prior distribution will be used.

Using the specific type of model, either the MNL or RPL probs will be returned.

Value

A matrix of probabilities for each alternative and choice task.

Calculate the MNL probabilities

Description

Calculate the MNL probabilities

Usage

probabilities_mnl(x)

Arguments

Value

A matrix of probabilities for each alternative and choice task. With Bayesian priors the return is the average probabilites over the prior distribution

Compute the radical inverse

Description

Equation 2 in Bhat (2003)

Usage

radical_inverse(n_dim, primes, count, digit, perms)

Arguments

References

Bhat, C. n_draws., 2003, Simulation Estimation of Mixed Descrete Choice Models Using Randomized and Scrambled Halton Sequences, Transportation Research Part B, 9, pp. 837-855

Make a random design

Description

Generates a random design by sampling from the candidate set each update of the algorithm.

Usage

random(
  design_object,
  model,
  efficiency_criteria,
  utility,
  prior_values,
  dudx,
  candidate_set,
  rows,
  save_designs,
  control
)

Arguments

Details

With no restrictions placed, this type of design will only consider efficiency. There is no guarantee that you will achieve attribute level balance, nor that all attribute levels will be present. More efficient designs tend to have more extreme trade-offs.

Value

A list of class 'spdesign'

Create a random design_object candidate

Description

Sample from the candidate set to create a random design_object. If level occurrences are specified, single rows are swapped with random rows from the candidate set until the design_object candidate satisfies them. A swap is kept if it does not move the design_object candidate further away from the level occurrences.

Usage

random_design_candidate(
  utility,
  candidate_set,
  rows,
  sample_with_replacement,
  print_counter = FALSE,
  max_attempts = 1e+05
)

Arguments

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

stats

vcov()

Relabeling of attribute levels

Description

Relabels the attribute levels to create a new design candidate. For example, if the column contains the levels (1, 2, 1, 3, 2, 3) and 1 and 3 are relabeled, then the column becomes (3, 2, 3, 1, 2, 1), i.e. 1 becomes 3 and 3 becomes 1.

Usage

relabel(x)

Arguments

Details

Will randomly sample 2 attribute levels that will be relabeled and the relabeling is done independently for each column, which implies that the same attribute will be relabeled differently depending on which alternative it belongs to.

References

Hensher, D. A., Rose, J. M. & Greene, W., 2005, Applied Choice Analysis, 2nd ed., Cambridge University Press

Removes all brackets

Description

Takes a string as input and removes everything between square and round brackets. The function wraps around remove_square_brackets and remove_round_brackets. To avoid problems, we first remove square brackets.

Usage

remove_all_brackets(string)

Arguments

Value

A string without brackets

Remove round bracket

Description

Removes everything between (and including) round brackets. We negating matches with I(), since this is R's interaction operator.

Usage

remove_round_brackets(string)

Arguments

Details

(?<!I) - A negative lookbehind for I

Remove square bracket

Description

Removes everything between (and including) square brackets

Usage

remove_square_brackets(string)

Arguments

Remove all white spaces

Description

Takes a string as an input and removes all whitespaces in the string

Usage

remove_whitespace(string)

Arguments

Value

A character vector with no white spaces

Repeat columns

Description

Repeats each column of the matrix or data frame 'x' a number of times equal to 'times'.

Usage

rep_cols(x, times)

Arguments

Value

A matrix or data.frame depending on the type of the input

Examples

test_matrix <- matrix(runif(12), 4)
rep_cols(test_matrix, 2)

Repeat rows

Description

Repeats each row in the matrix or data frame 'x' a number of times equal to 'times'.

Usage

rep_rows(x, times)

Arguments

Value

A matrix or data.frame depending on type of the input

Examples

test_matrix <- matrix(runif(12), 4)
rep_rows(test_matrix, 2)

Make a design candidate based on the rsc algorithm

Description

Depending on the setting the function calls a combination of relabel, swap and cycle to create new design candidates. The code is intentionally written modular to allow for all special cases of the algorithm.

Usage

rsc(
  design_object,
  model,
  efficiency_criteria,
  utility,
  prior_values,
  dudx,
  candidate_set,
  rows,
  save_designs,
  control
)

Arguments

Sets the default level occurrence in an attribute level balanced design

Description

The function sets the default level occurrence of an attribute when a design is restricted to be attribute level balanced. If the design cannot be attribute level balanced, then the restriction will be relaxed for each attribute failing to meet this criteria. Specifically, the code will impose a minimum range of how often an attribute level can occur. This will secure that the design is near attribute level balanced. In this case a warning is issued.

Usage

set_default_level_occurrence(n_lvls, rows)

Arguments

Value

A named list of lists where the top level gives the attribute and the lower level gives the times or range each attribute level should occur in the design

Validate design opt

Description

The function takes the list of design options and adds default values where none are specified. This function is exported, but is not intended to be called by the user of the package. The function is called from within generate_design to populate the list with sensible defaults

Usage

set_default_options(opts_input)

Arguments

Value

A list of design options populated by sensible default values

Shuffle the order of points in the unit interval.

Description

Shuffle the order of points in the unit interval.

Usage

shuffle(x)

Arguments

Create a summary of the experimental design

Description

Create a summary of the experimental design

Usage

## S3 method for class 'spdesign'
summary(object, ...)

Arguments

Value

No return value. Prints a summary of the 'spdesign' object to the console

Swapping of attribute

Description

Swaps the order of the attributes to create a new design candidate. For example, if the attributes in the first and fourth choice situation (row) are swapped, then (1, 2, 1, 3, 2, 3) becomes( 3, 2, 1, 1, 2, 3).

Usage

swap(x)

Arguments

Details

The algorithm randomly samples 2 row positions that are swapped and the swaps are independent across attributes and alternatives

References

Hensher, D. A., Rose, J. M. & Greene, W., 2005, Applied Choice Analysis, 2nd ed., Cambridge University Press

Check if the design is too small

Description

Uses the formula of T * (J - 1) to check if the design is large enough to identify the parameters of the utility function.

Usage

too_small(x, rows)

Arguments

Value

A boolean equal to 'TRUE' if the design is too small

Transform distribution

Description

Transform distribution

Usage

transform_distribution(mu, sigma, eta, type)

Arguments

Value

A vector with the transformed distribution given the parameters

Transform to the lognormal distribution

Description

Transform to the lognormal distribution

Usage

transform_lognormal(mu, sigma, eta)

Arguments

Transform to the normal distribution

Description

Transform to the normal distribution

Usage

transform_normal(mu, sigma, eta)

Arguments

Transform to the triangular distribution

Description

Transform to the triangular distribution

Usage

transform_triangular(mu, sigma, eta)

Arguments

Transform to the uniform distribution

Description

Transform to the uniform distribution

Usage

transform_uniform(mu, sigma, eta)

Arguments

Find attributes with level occurrences and levels that are not listed

Description

A supplied candidate set may contain attribute levels that are not listed in the utility functions. This is only a problem for attributes with level occurrences specified, because occurrences can only be counted for listed levels.

Usage

unlisted_levels(utility, candidate_set, rows)

Arguments

Value

A character vector with the names of the attributes with level occurrences specified, where the candidate set contains levels that are not listed in the utility functions. Empty if there are none.

Update the utility function

Description

Updates the utility function to consider dummy coded attributes. It will expand the dummy-coding to K-1 dropping the lowest level. This is consistent with standard practice.

Usage

update_utility(x)

Arguments

Details

The function is called prior to evaluating designs if dummy-coded attributes are present in the utility function. This is because the utility function is evaluated in the context of the design environment and must be added there

Important to note about the naming of the expanded priors and attributes: The names for the attributes will be attached with the level of the factor, whereas the prior will be named corresponding to the level, e.g., 2, 3, 4. This is simply the result of the difference between how it's extracted from the utility functions and how model.matrix creates names.

Value

An updated cleaned utility expression

Create formulas from the utility functions

Description

Create formulas from the utility functions such that we can create correct model matrices. The formula of each utility function contains its terms, i.e. the utility function without the parameters.

Usage

utility_formula(x)

Arguments

Details

Note that the formulas are created from the cleaned utility expression and **not** the updated utility expression. This is because we are converting dummy coded attributes to factors prior to calling model.matrix. This ensures that dummy coded attributes are correctly returned with the model matrix.

Value

A list of formula expressions for the utility functions

Extract the variance co-variance matrix

Description

A generic method for extracting the variance covariance matrix from a design object

Usage

## S3 method for class 'spdesign'
vcov(object, ...)

Arguments

Value

A matrix with row- and column names equal to the parameter names