Calculate probabilities of a Decision Field Theory (DFT) with external thresholds.
apollo_dft(dft_settings, functionality)List of settings for the DFT model. It should contain the following elements.
alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar.
avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1.
choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.
attrValues: A named list with as many elements as alternatives. Each element is itself a named list of vectors of the alternative attributes for each observation (usually a column from the database). All alternatives must have the same attributes (can be set to zero if not relevant).
altStart: A named list with as many elements as alternatives. Each elment can be a scalar or vector containing the starting preference value for the alternative.
attrWeights: A named list with as many elements as attributes, or fewer. Each element is the weight of the attribute, and can be a scalar, a vector with as many elements as observations, or a matrix/array if random. They should add up to one for each observation and draw (if present), and will be re-scaled if they do not. attrWeights and attrScalings are incompatible, and they should not be both defined for an attribute. Default is 1 for all attributes.
attrScalings: A named list with as many elements as attributes, or fewer. Each element is a factor that scale the attribute, and can be a scalar, a vector or a matrix/array. They do not need to add up to one for each observation. attrWeights and attrScalings are incompatible, and they should not be both defined for an attribute. Default is 1 for all attributes.
procPars: A list containing the four DFT 'process parameters'
error_sd: Numeric scalar or vector. The standard deviation of the the error term in each timestep.
timesteps: Numeric scalar or vector. Number of timesteps to consider. Should be an integer bigger than 0.
phi1: Numeric scalar or vector. Sensitivity.
phi2: Numeric scalar or vector. Process parameter.
rows: Boolean vector. Consideration of rows in the likelihood calculation, FALSE to exclude. Length equal to the number of observations (nObs). Default is "all", equivalent to rep(TRUE, nObs).
Character. Can take different values depending on desired output.
"estimate": Used for model estimation.
"prediction": Used for model predictions.
"validate": Used for validating input.
"zero_LL": Used for calculating null likelihood.
"conditionals": Used for calculating conditionals.
"output": Used for preparing output after model estimation.
"raw": Used for debugging.
The returned object depends on the value of argument functionality as follows.
"estimate": vector/matrix/array. Returns the probabilities for the chosen alternative for each observation.
"prediction": List of vectors/matrices/arrays. Returns a list with the probabilities for all alternatives, with an extra element for the chosen alternative probability.
"validate": Boolean. Returns TRUE if all tests are passed.
"zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.
"conditionals": Same as "prediction".
"output": Same as "estimate" but also writes summary of choices into temporary file (later read by apollo_modelOutput).
"raw": Same as "prediction".
Hancock, T.; Hess, S. and Choudhury, C. (2018) Decision field theory: Improvements to current methodology and comparisons with standard choice modelling techniques. Transportation Research 107B, 18 - 40. Hancock, T.; Hess, S. and Choudhury, C. (Submitted) An accumulation of preference: two alternative dynamic models for understanding transport choices. Roe, R.; Busemeyer, J. and Townsend, J. (2001) Multialternative decision field theory: A dynamic connectionist model of decision making. Psychological Review 108, 370