idefix (version 0.4.0)

Modfed: Modified Federov algorithm for MNL models.

Description

The algorithm swaps every profile of an initial start design with candidate profiles. By doing this, it tries to minimize the D(B)-error, based on a multinomial logit model. This routine is repeated for multiple starting designs.

Usage

Modfed(cand.set, n.sets, n.alts, par.draws, alt.cte = NULL,
  no.choice = FALSE, start.des = NULL, parallel = TRUE,
  max.iter = Inf, n.start = 12, best = TRUE)

Arguments

cand.set

A numeric matrix in which each row is a possible profile. The Profiles function can be used to generate this matrix.

n.sets

Numeric value indicating the number of choice sets.

n.alts

Numeric value indicating the number of alternatives per choice set.

par.draws

A matrix or a list, depending on alt.cte.

alt.cte

A binary vector indicating for each alternative whether an alternative specific constant is desired. The default is NULL.

no.choice

A logical value indicating whether a no choice alternative should be added to each choice set. The default is FALSE.

start.des

A list containing one or more matrices corresponding to initial start design(s). The default is NULL.

parallel

Logical value indicating whether computations should be done over multiple cores. The default is TRUE.

max.iter

A numeric value indicating the maximum number allowed iterations. The default is Inf.

n.start

A numeric value indicating the number of random start designs to use. The default is 12.

best

A logical value indicating whether only the best design should be returned. The default is TRUE.

Value

If best = TRUE the design with the lowest D(B)-error is returned. If best = FALSE, the results of all (provided) start designs are returned.

design

A numeric matrix wich contains an efficient design.

error

Numeric value indicating the D(B)-error of the design.

inf.error

Numeric value indicating the percentage of draws for which the D-error was Inf.

probs

Numeric matrix containing the probabilities of each alternative in each choice set. If a sample matrix was provided in par.draws, this is the average over all draws.

Details

Each iteration will loop through all profiles from the initial design, evaluating the change in D(B)-error for every profile from cand.set. The algorithm stops when an iteration occured without replacing a profile or when max.iter is reached.

By specifying a numeric vector in par.draws, the D-error will be calculated and the design will be optimised locally. By specifying a matrix, in which each row is a draw from a multivariate distribution, the DB-error will be calculated, and the design will be optimised globally. Whenever there are alternative specific constants, par.draws should be a list containing two matrices: The first matrix containing the parameter draws for the alternative specific constant parameters. The second matrix containing the draws for the rest of the parameters.

The DB-error is calculated by taking the mean over D-errors. It could be that for some draws the design results in an infinite D-error. The percentage of draws for which this was true for the final design can be found in the output inf.error.

Alternative specific constants can be specified in alt.cte. The length of this binary vector should equal n.alts, were 0 indicates the absence of an alternative specific constant and 1 the opposite.

start.des is a list with one or several matrices corresponding to initial start design(s). In each matrix each row is a profile. The number of rows equals n.sets * n.alts, and the number of columns equals the number of columns of cand.set + the number of non-zero elements in alt.cte. If start.des = NULL, n.start random initial designs will be generated. If start designs are provided, n.start is ignored.

If no.choice is TRUE, in each choice set an alternative with one alternative specific constant is added. The return value of the D(B)-error is however based on the design without the no choice option.

When parallel is TRUE, detectCores will be used to decide upon the number of available cores. That number minus 1 cores will be used to search for efficient designs. The computation time will decrease significantly when parallel = TRUE.

Examples

# NOT RUN {
# DB-efficient designs
# 3 Attributes, all dummy coded. 1 alternative specific constant = 7 parameters
cand.set <- Profiles(lvls = c(3, 3, 3), coding = c("D", "D", "D"))
mu <- c(0.5, 0.8, 0.2, -0.3, -1.2, 1.6, 2.2) # Prior parameter vector
v <- diag(length(mu)) # Prior variance.
set.seed(123) 
pd <- MASS::mvrnorm(n = 10, mu = mu, Sigma = v) # 10 draws.
p.d <- list(matrix(pd[,1], ncol = 1), pd[,2:7])
Modfed(cand.set = cand.set, n.sets = 8, n.alts = 2, 
       alt.cte = c(1, 0), parallel = FALSE, par.draws = p.d, best = FALSE)

# DB-efficient design with start design provided.  
# 3 Attributes with 3 levels, all dummy coded (= 6 parameters).
cand.set <- Profiles(lvls = c(3, 3, 3), coding = c("D", "D", "D")) 
mu <- c(0.8, 0.2, -0.3, -0.2, 0.7, 0.4) # Prior mean (total = 5 parameters).
v <- diag(length(mu)) # Prior variance.
sd <- list(example_design)
set.seed(123)
ps <- MASS::mvrnorm(n = 10, mu = mu, Sigma = v) # 10 draws.
Modfed(cand.set = cand.set, n.sets = 8, n.alts = 2, 
       alt.cte = c(0, 0), parallel = FALSE, par.draws = ps, start.des = sd)
# }