# Model file examples

#### 2020-03-16

Apollo is an R package designed for estimation and analysis of choice models (Train, 2008). This package allows estimating Multinomial logit (MNL), Nested logit (NL), cross-nested logit (CNL), exploded logit (EL), ordered logit (OL), Integrated Choice and Latent Variable (ICLV, Ben-Akiva et al. 2002), Multiple Discrete-Continuous Extreme Value (MDCEV, Bhat 2008), nested MDCEV (MDCNEV, Pinjari and Bhat 2010), and Decision Field Theory (DFT, Hancock and Hess 2018) models. All models support both continuous and discrete mixing (e.g. continuous random parameters, latent classes or finite mixtures), both between and within individuals (i.e at the individual and observation level). Different models can be easily combined for joint estimation. The package allows for classical estimation (i.e. maximum likelihood) as well as Bayesian estimation (i.e. hierarchical Bayes, through package RSGHB).

All functionalities are described in the manual, available at www.ApolloChoiceModelling.com. Examples can also be found on the website.

## MMNL model file example

In this section, we present code to estimate a mixed MNL model (MMNL) using the synthetic data included in the package. After estimation, we predict the effect of a 10% increase in the train fares. The utility function of the model remains the same than in the previous example, i.e.:

$U_{nsi} = asc_i + \beta_{tt}tt_{nsi} + \beta_{c}*cost_{nsi} + \varepsilon_{nsi}$

Where n indexes individuals, s choice scenarios, and i alternatives. $$asc_i$$ is the alternative specific constant, $$tt_{nsi}$$ is the travel time and $$cost_{nsi}$$ is the cost. $$\varepsilon_{nsi}$$ is an independent identically distributed standard Gumbel error term. $$\beta_{tt}$$ follows a log-normal distribution with the underlying normal having a mean $$\mu_{tt}$$ and standard deviation $$\sigma_{tt}$$. $$asc_i$$, $$\beta_{c}$$, $$\mu_{tt}$$ and $$\sigma_{tt}$$ are parameters to be estimated.

The likelihood function of this model for individual $$n$$ is as follows.

$L_{n}=\int_{\beta_{tt}}\prod_{s}P_{nsi}f(\beta_{tt})d\beta_{tt}$

Where $$P_{nsi}=\frac{e^{V_{nsi}}}{\sum_{j}e^{V_{nsj}}}$$, $$V_{nsi}=U_{nsi}-\varepsilon_{nsi}$$, and $$f$$ is the probability density function of $$\beta_{tt}$$. As this function does not have an analytical closed form, we estimate it using Monte Carlo integration, i.e.:

$L_{n}\approx\frac{1}{R}\sum_{\beta_{tt}^r}\prod_{s}P_{nsi}^r$ Where $$P_{nsi}^r=P_{nsi}(\beta_{tt}^r)$$, with $$\beta_{tt}^r$$ a random draw of $$\beta_{tt}$$ from its distribution $$f$$, and R is a big number.

The code is very similar to the previous example, with only sections 1 and 3 changing. * In section 1 we set mixing = TRUE inside apollo_control, and we set nCores = 2 to speed up estimation by using two computing threads (this is not mandatory). * In section 3 we define the mean (b_tt_mu) and standar deviation (b_tt_sigma) of the underlying normal distribution. We then define the type, name and number of draws used. Finally, we construct the random coefficient $$\beta_{tt}$$ inside a function called apollo_randCoeff. We use 500 inter-individual draws that come from a standard normal distribution, which we later transform into log-normals inside apollo_randCoeff.

Even though in this case we only use inter-individual draws, note that inter and intra-individuals draws can be used simultaneously. Inter-individual draws capture variability between individuals, while intra-individual draws capture variability within individuals. In terms of the Monte Carlo integration, inter-individual draws are common for all observations from the same individual, while intra-individual draws are different for each observations. In terms of the likelihood function, the use of intra-individual draws would lead to $$L_{n}\approx\prod_{s}\frac{1}{R}\sum_{\beta_{tt}^r}P_{nsi}$$, which is not the case in this model.

Estimation of models with mixing is computationally more demanding than models without mixing. Furthermore, using both inter and intra-individual requires large amounts of memory, which can further slow the estimation process. For this reason, this example is not run automatically. Yet, the users may copy and paste the code in a script, and run it themselves.

# ####################################################### #
#### 1. Definition of core settings
# ####################################################### #

### Clear memory
rm(list = ls())

library(apollo)

### Initialise code
apollo_initialise()

### Set core controls
apollo_control = list(
modelName  ="MMNL",
modelDescr ="Simple MMNL model on mode choice SP data",
indivID    ="ID",
mixing     = TRUE,
nCores     = 2
)

# ####################################################### #
# ####################################################### #

data("apollo_modeChoiceData")
database = apollo_modeChoiceData
rm(apollo_modeChoiceData)

### Use only SP data
database = subset(database,database$SP==1) ### Create new variable with average income database$mean_income = mean(database$income) # ####################################################### # #### 3. Parameter definition #### # ####################################################### # ### Vector of parameters, including any that are kept fixed ### during estimation apollo_beta=c(asc_car = 0, asc_bus = 0, asc_air = 0, asc_rail = 0, mu_tt = 0, sigma_tt = 1, b_c = 0) ### Vector with names (in quotes) of parameters to be ### kept fixed at their starting value in apollo_beta. ### Use apollo_beta_fixed = c() for no fixed parameters. apollo_fixed = c("asc_car") ### Set parameters for generating draws apollo_draws = list( interDrawsType = "halton", interNDraws = 500, interUnifDraws = c(), interNormDraws = c("draws_tt"), intraDrawsType = "halton", intraNDraws = 0, intraUnifDraws = c(), intraNormDraws = c() ) ### Create random parameters apollo_randCoeff = function(apollo_beta, apollo_inputs){ randcoeff = list() randcoeff[["b_tt"]] = -exp(mu_tt + sigma_tt*draws_tt) return(randcoeff) } # ####################################################### # #### 4. Input validation #### # ####################################################### # apollo_inputs = apollo_validateInputs() # ####################################################### # #### 5. Likelihood definition #### # ####################################################### # apollo_probabilities=function(apollo_beta, apollo_inputs, functionality="estimate"){ ### Attach inputs and detach after function exit apollo_attach(apollo_beta, apollo_inputs) on.exit(apollo_detach(apollo_beta, apollo_inputs)) ### Create list of probabilities P P = list() ### List of utilities: these must use the same names as ### in mnl_settings, order is irrelevant. V = list() V[['car']] = asc_car + b_tt*time_car + b_c*cost_car V[['bus']] = asc_bus + b_tt*time_bus + b_c*cost_bus V[['air']] = asc_air + b_tt*time_air + b_c*cost_air V[['rail']] = asc_rail + b_tt*time_rail + b_c*cost_rail ### Define settings for MNL model component mnl_settings = list( alternatives = c(car=1, bus=2, air=3, rail=4), avail = list(car=av_car, bus=av_bus, air=av_air, rail=av_rail), choiceVar = choice, V = V ) ### Compute probabilities using MNL model P[['model']] = apollo_mnl(mnl_settings, functionality) ### Take product across observation for same individual P = apollo_panelProd(P, apollo_inputs, functionality) ### Average draws P = apollo_avgInterDraws(P, apollo_inputs, functionality) ### Prepare and return outputs of function P = apollo_prepareProb(P, apollo_inputs, functionality) return(P) } # ####################################################### # #### 6. Model estimation and reporting #### # ####################################################### # model = apollo_estimate(apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs) apollo_modelOutput(model) apollo_saveOutput(model) # ####################################################### # #### 7. Postprocessing of results #### # ####################################################### # ### Use the estimated model to make predictions predictions_base = apollo_prediction(model, apollo_probabilities, apollo_inputs) ### Now imagine the cost for rail increases by 10% ### and predict again database$cost_rail = 1.1*database\$cost_rail
predictions_new = apollo_prediction(model,
apollo_probabilities,
apollo_inputs)

### Compare predictions
change=(predictions_new-predictions_base)/predictions_base
### Not interested in chosen alternative now,
### so drop last column
change=change[,-ncol(change)]
### Summary of changes (possible presence of NAs due to
### unavailable alternatives)
summary(change)

## References

• Ben-Akiva, M. and Lerman, S. (1985) Discrete Choice Analysis. Cambridge, Massachusetts. The MIT Press. ISBN 978-0-262-02217-0
• Ben-Akiva, M.; McFadden, D.; Train, K.; Walker, J.; Bhat, C.; Bierlaire, M.; Bolduc, D.; Boersch-Supan, A.; Brownstone, D.; Bunch, D.; Daly, A.; De Palma, A.; Gopinath, D.; Karlstrom, A.; Munizaga, M. (2002) Hybrid Choice Models: Progress and Challenges. Marketing Letters 13, 163 - 175.
• Bhat, C. (2008) The multiple discrete-continuous extreme value (MDCEV) model: Role of utility function parameters, identification considerations,and model extensions. Transportation Research 42B, 274 - 303.
• 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.
• Pinjari, A. and Bhat, C. (2010) A multiple discrete–continuous nested extreme value (MDCNEV) model: Formulation and application to non-worker activity time-use and timing behavior on weekdays. Transportation Research 44B, 562 - 583.
• Train, K. (2009) Discrete Choice Methods with Simulation, 2nd edition. New York, New York. Cambridge University Press. ISBN 978-0-521-76655-5