idefix (version 0.4.0)

SeqMOD: Sequential modified federov algorithm for MNL model.

Description

Selects the choice set that minimizes the DB-error when added to an initial design, given (updated) parameter values.

Usage

SeqMOD(des = NULL, cand.set, n.alts, par.draws, prior.covar,
  alt.cte = NULL, no.choice = NULL, weights = NULL,
  parallel = TRUE, reduce = TRUE, allow.rep = FALSE)

Arguments

des

A design matrix in which each row is a profile. If alternative specific constants are present, those should be included as the first column(s) of the design. Can be generated with Modfed or CEA.

cand.set

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

n.alts

Numeric value indicating the number of alternatives per choice set.

par.draws

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

prior.covar

Covariance matrix of the prior distribution.

alt.cte

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

no.choice

An integer indicating the no choice alternative. The default is NULL.

weights

A vector containing the weights of the draws. Default is NULL, See also ImpsampMNL.

parallel

Logical value indicating whether computations should be done over multiple cores.

reduce

Logical value indicating whether the candidate set should be reduced or not.

allow.rep

Logical value indicating whether repeated choice sets are allowed in the design.

Value

set

A matrix representing a DB efficient choice set.

error

A numeric value indicating the DB-error of the whole design.

Details

This algorithm is ideally used in an adaptive context. The algorithm will select the next DB-efficient choice set given parameter values and possible previously generated choice sets. In an adaptive context these parameter values are updated after each observed response.

Previously generated choice sets, which together form an initial design, can be provided in des. When no design is provided, the algorithm will select te most efficient choice set based on the fisher information of the prior covariance matrix prior.covar.

If alt.cte = NULL, par.draws should be a matrix in which each row is a sample from the multivariate parameter distribution. In case that alt.cte is not NULL, a list containing two matrices should be provided to par.draws. The first matrix containing the parameter draws for the alternative specific parameters. The second matrix containing the draws for the rest of the parameters.

The list of potential choice sets are created using combn. If reduce is TRUE, allow.rep = FALSE and vice versa. Furthermore, the list of potential choice sets will be screaned in order to select only those choice sets with a unique information matrix. If no alternative specific constants are used, reduce should always be TRUE. When alternative specific constants are used reduce can be TRUE so that the algorithm will be faster, but the combinations of constants and profiles will not be evaluated exhaustively.

The weights argument can be used when the par.draws have weights. This is for example the case when parameter values are updated using ImpsampMNL.

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 the optimal choice set. For small problems (6 parameters), parallel = TRUE can be slower. For larger problems the computation time will decrease significantly.

Note: this function is more stable than SeqCEA, but it takes more time to get the output. This happens because this function makes an exhaustive search to get the choice set, whereas SeqCEA makes a random search.

References

juidefix

Examples

# NOT RUN {
# DB efficient choice set, given a design and parameter draws. 
# Candidate profiles 
cs <- Profiles(lvls = c(3, 3, 3), coding = c("D", "D", "D"))
m <- c(0.3, 0.2, -0.3, -0.2, 1.1, 2.4) # mean (total = 6 parameters).
pc <- diag(length(m)) # covariance matrix
set.seed(123)
sample <- MASS::mvrnorm(n = 10, mu = m, Sigma = pc)
# Initial design.
des <- example_design 
# Efficient choice set to add. 
SeqMOD(des = des, cand.set = cs, n.alts = 2, par.draws = sample, 
           prior.covar = pc, parallel = FALSE)

# DB efficient choice set, given parameter draws. 
# with alternative specific constants 
des <- example_design2 
cs <- Profiles(lvls = c(3, 3, 3), coding = c("D", "D", "D"))
ac <- c(1, 1, 0) # Alternative specific constants. 
m <- c(0.3, 0.2, -0.3, -0.2, 1.1, 2.4, 1.8, 1.2) # mean 
pc <- diag(length(m)) # covariance matrix
pos <- MASS::mvrnorm(n = 10, mu = m, Sigma = pc)
sample <- list(pos[ , 1:2], pos[ , 3:8])
# Efficient choice set. 
SeqMOD(des = des, cand.set = cs, n.alts = 3, par.draws = sample, alt.cte = ac, 
           prior.covar = pc, parallel = FALSE)
# }