apollo_dft {apollo}

Calculate DFT probabilities

Description

Calculate probabilities of a Decision Field Theory (DFT) model and can also perform other operations based on the value of the functionality argument.

Usage

apollo_dft(dft_settings, functionality)

Arguments

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. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• altStart: A named list with as many elements as alternatives. Each element can be a scalar or vector containing the starting preference value for the alternative.

• 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.

• 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).

• 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.

• choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• 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 which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

functionality

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

Value

The returned object depends on the value of argument functionality as follows.

• "components": Same as "estimate"

• "conditionals": Same as "estimate"

• "estimate": vector/matrix/array. Returns the probabilities for the chosen alternative for each observation.

• "gradient": Not implemented.

• "output": Same as "estimate" but also writes summary of input data to internal Apollo log.

• "prediction": List of vectors/matrices/arrays. Returns a list with the probabilities for all alternatives, with an extra element for the chosen alternative probability.

• "preprocess": Returns a list with pre-processed inputs, based on dft_settings.

• "raw": Same as "prediction"

• "report": Choice overview.

• "shares_LL": Not implemented. Returns a vector of NA with as many elements as observations.

• "validate": Same as "estimate"

• "zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.

References

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