apollo_mdcev {apollo}

Calculates MDCEV likelihoods

Description

Calculates the likelihoods of a Multiple Discrete Continuous Extreme Value (MDCEV) model and can also perform other operations based on the value of the functionality argument.

Usage

apollo_mdcev(mdcev_settings, functionality)

Arguments

mdcev_settings

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• alpha: Named list. Alpha parameters for each alternative, including for any outside good. As many elements as alternatives.

• alternatives: Character vector. Names of alternatives, elements must match the names in list 'utilities'.

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

• budget: Numeric vector. Budget for each observation.

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

• continuousChoice: Named list of numeric vectors. Amount of consumption of each alternative. One element per alternative, as long as the number of observations or a scalar. Names must match those in alternatives.

• cost: Named list of numeric vectors. Price of each alternative. One element per alternative, each one as long as the number of observations or a scalar. Names must match those in alternatives.

• gamma: Named list. Gamma parameters for each alternative, excluding any outside good. As many elements as inside good alternatives.

• nRep: Numeric scalar. Number of simulations of the whole dataset used for forecasting. The forecast is the average of these simulations. Default is 100.

• outside: Character. Optional name of the outside good.

• rawPrediction: Logical scalar. TRUE for prediction to be returned at the draw level (a 3-dim array). FALSE for prediction to be returned averaged across draws. Default is FALSE.

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

• sigma: Numeric scalar. Scale parameter of the model extreme value type I error.

• utilities: Named list. Utilities of the alternatives. Names of elements must match those in argument 'alternatives'.

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 observed consumption for each observation.

• "gradient": Not implemented

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

• "prediction": A matrix with one row per observation, and columns indicating means and s.d. of continuous and discrete predicted consumptions.

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

• "raw": Same as "estimate"

• "report": Dependent variable overview.

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

• "validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.

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