apollo_dft: Calculate DFT probabilities
In byu-transpolab/apollo: Tools for Choice Model Estimation and Application

Description Usage Arguments Value References

Calculate probabilities of a Decision Field Theory (DFT) with external thresholds.

1	apollo_dft(dft_settings, functionality)

dft_settings

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).
componentName: Character. Name given to model component.

functionality

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": Same as "estimate"
"zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.
"conditionals": Same as "estimate"
"output": Same as "estimate" but also writes summary of input data to internal Apollo log.
"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

byu-transpolab/apollo documentation built on Dec. 19, 2021, 12:48 p.m.