The recommended way to use Apollo is to create different R scripts for each model the user wants to estimate. These scripts are refer to as model files and contain all the necessary information to estimate the model (except for the data), and can also include post-estimation analysis of the results.
A model file should be structured around the following sections:
Definition of core settings: In this section the Apollo library is loaded, and global variables such as the name of the model are defined.
Data loading: In this section the database is loaded. Any transformation to the data that does not chaneg throughout estimation (e.g. averages) should be performed here and stored inside the database object.
Parameter definition: In this section, a vector containing the names and starting values of parameter is defined, as well as details of their mixing distribution distributions if present.
Input validation: In this section, all inputs prepared in the previous sections are validated and stored toghether.
Likelihood definition: In this section, the user must write the a function that calculate the model likelihood.
Model estimation and reporting: In this section, the model is estimated and the results are displayed.
Postprocessing of results: This is an optional section where the user can do forecasting and other post-processing of the results.
In this document, we present two example model files: a multinomial logit (MNL) model, and a mixed multinomial logit (MMNL) model. More examples, discussed with higher level of detail are available at www.apolloChoiceModelling.com.
Apollo allows estimating Multinomial logit (MNL), Nested logit (NL), cross-nested logit (CNL), exploded logit (EL), ordered logit (OL), Integrated Choice and Latent Variable (ICLV), Multiple Discrete-Continuous Extreme Value (MDCEV), nested MDCEV (MDCNEV), and Decision Field Theory (DFT) models. The user can introduce continuous or discrete mixing (i.e. latent classes or finite mixtures) in all these kinds of models, both between and within individuals. Different models can be combined for join estimation. All these functionalities are described in the manual, available at the www.apolloChoiceModelling.com website.
In this section, we present code to estimate an MNL model using the synthetic data included in the package. In the postprocessing, we predict and study the impact of a 10% increase in the cost of the train fare. The utility functions of alternatives are defined as follows.
\[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_{si}\) is the travel time and \(cost_{si}\) is the cost. \(\varepsilon_{nsi}\) is an independent identically distributed standard Gumbel error term. \(asc_i\), \(\beta_{tt}\) and \(\beta_{c}\) are parameters to be estimated.
The likelihood function of this model for individual \(n\) is as follows.
\[L_{n}=\prod_{s}P_{nsi}\]
Where \[P_{nsi}=\frac{e^{V_{nsi}}}{\sum_{j}e^{V_{nsj}}}\] And \(V_{nsi}=U_{nsi}-\varepsilon_{nsi}\), i.e. the deterministic part of the utility.
The likelihood function of the MNL model is pre-coded in Apollo, so we do not need to type it ourselves. However, if the user prefers to write the likelihood themself, they can also do it. The pre-coded MNL likelihood function (apollo_mnl) requires a series of inputs defined inside the mnl_settings object.
# ####################################################### #
#### 1. Definition of core settings
# ####################################################### #
### Clear memory
rm(list = ls())
### Load libraries
library(apollo)
### Initialise code
apollo_initialise()
### Set core controls
apollo_control = list(
modelName ="MNL",
modelDescr ="Simple MNL model on mode choice SP data",
indivID ="ID"
)
# ####################################################### #
#### 2. Data loading ####
# ####################################################### #
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,
b_tt_car = 0,
b_tt_bus = 0,
b_tt_air = 0,
b_tt_rail= 0,
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")
# ####################################################### #
#### 4. Input validation ####
# ####################################################### #
apollo_inputs = apollo_validateInputs()
#> Missing setting for mixing, set to default of FALSE
#> Missing setting for nCores, set to default of 1
#> Missing setting for workInLogs, set to default of FALSE
#> Missing setting for seed, set to default of 13
#> Missing setting for HB, set to default of FALSE
#> Several observations per individual detected based on the value of ID.
#> Setting panelData set to TRUE.
#> All checks on apollo_control completed.
#> All checks on data completed.
# ####################################################### #
#### 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_car *time_car + b_c*cost_car
V[['bus']] = asc_bus + b_tt_bus *time_bus + b_c*cost_bus
V[['air']] = asc_air + b_tt_air *time_air + b_c*cost_air
V[['rail']]= asc_rail+ b_tt_rail*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)
### 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)
#> Testing probability function (apollo_probabilities)
#>
#> All checks passed for MNL model component
#> Overview of choices for MNL model component:
#> car bus air rail
#> Times available 5446.00 6314.00 5264.00 6118.00
#> Times chosen 1946.00 358.00 1522.00 3174.00
#> Percentage chosen overall 27.80 5.11 21.74 45.34
#> Percentage chosen when available 35.73 5.67 28.91 51.88
#>
#>
#>
#> Starting main estimation
#> Initial function value: -8196.021
#> Initial gradient value:
#> asc_bus asc_air asc_rail b_tt_car b_tt_bus b_tt_air
#> -1599.667 -39.000 1302.667 92447.083 -597397.501 -1820.833
#> b_tt_rail b_c
#> 189332.083 8862.500
#> initial value 8196.020532
#> iter 2 value 7456.688617
#> iter 3 value 7375.154805
#> iter 4 value 7260.844459
#> iter 5 value 6670.816191
#> iter 6 value 6618.448416
#> iter 7 value 6471.224865
#> iter 8 value 6429.069517
#> iter 9 value 6216.357939
#> iter 10 value 6052.604912
#> iter 11 value 5838.718119
#> iter 12 value 5815.462122
#> iter 13 value 5804.515622
#> iter 14 value 5802.299705
#> iter 15 value 5802.031103
#> iter 16 value 5802.023289
#> iter 17 value 5802.022828
#> iter 17 value 5802.022826
#> iter 17 value 5802.022826
#> final value 5802.022826
#> converged
#>
#> Estimated values:
#> [,1]
#> asc_car 0.0000
#> asc_bus 0.0115
#> asc_air -0.6495
#> asc_rail -1.2357
#> b_tt_car -0.0101
#> b_tt_bus -0.0164
#> b_tt_air -0.0118
#> b_tt_rail -0.0048
#> b_c -0.0529
#>
#> Computing covariance matrix using numDeriv package.
#> (this may take a while)
#> 0%....25%....50%....75%....100%
#> Hessian calculated with numDeriv will be used.
#> Calculating LL(0)... -8196.02
#> Updating inputs... Done.
#> Calculating LL of each model component...Done.
apollo_modelOutput(model)
#> Model run using Apollo for R, version 0.0.6
#> www.apollochoicemodelling.com
#>
#> Model name : MNL
#> Model description : Simple MNL model on mode choice SP data
#> Model run at : 2019-03-13 17:13:17
#> Estimation method : bfgs
#> Model diagnosis : successful convergence
#> Number of individuals : 500
#> Number of observations : 7000
#> Estimated parameters : 8
#> Model with no mixing
#>
#> LL(start) : -8196.021
#> LL(0) : -8196.021
#> LL(final) : -5802.023
#> Rho-square (0) : 0.2921
#> Adj.Rho-square (0) : 0.2911
#> AIC : 11620.05
#> BIC : 11674.87
#> Time taken (hh:mm:ss) : 00:00:20.37
#> Iterations : 19
#> Number of cores used : 1
#>
#> Estimates:
#> Estimate Std.err. t.ratio(0) Rob.std.err. Rob.t.ratio(0)
#> asc_car 0.0000 NA NA NA NA
#> asc_bus 0.0115 0.5408 0.02 0.5411 0.02
#> asc_air -0.6495 0.2699 -2.41 0.2666 -2.44
#> asc_rail -1.2357 0.3218 -3.84 0.3125 -3.95
#> b_tt_car -0.0101 0.0006 -15.75 0.0007 -15.30
#> b_tt_bus -0.0164 0.0015 -11.30 0.0015 -11.11
#> b_tt_air -0.0118 0.0024 -4.93 0.0024 -5.00
#> b_tt_rail -0.0048 0.0016 -2.90 0.0016 -2.95
#> b_c -0.0529 0.0014 -37.21 0.0017 -31.14
#>
#>
#> Overview of choices for MNL model component:
#> car bus air rail
#> Times available 5446.00 6314.00 5264.00 6118.00
#> Times chosen 1946.00 358.00 1522.00 3174.00
#> Percentage chosen overall 27.80 5.11 21.74 45.34
#> Percentage chosen when available 35.73 5.67 28.91 51.88
#>
apollo_saveOutput(model)
#> Estimates saved to MNL_estimates.csv
#> Classical covariance matrix saved to MNL_covar.csv
#> Robust covariance matrix saved to MNL_robcovar.csv
#> Classical correlation matrix saved to MNL_covar.csv
#> Robust correlation matrix saved to MNL_robcorr.csv
#> Model object saved to MNL.rds
# ####################################################### #
#### 7. Postprocessing of results ####
# ####################################################### #
### Use the estimated model to make predictions
predictions_base = apollo_prediction(model,
apollo_probabilities,
apollo_inputs)
#> Updating inputs...Done.
#> Running predictions from model... Done.
### 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)
#> Updating inputs...Done.
#> Running predictions from model... Done.
### 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)
#> car bus air rail
#> Min. :0.0000 Min. :0.0000 Min. :0.0000 Min. :-0.3028
#> 1st Qu.:0.0725 1st Qu.:0.0738 1st Qu.:0.0704 1st Qu.:-0.2060
#> Median :0.1168 Median :0.1218 Median :0.1100 Median :-0.1340
#> Mean :0.1105 Mean :0.1225 Mean :0.1121 Mean :-0.1434
#> 3rd Qu.:0.1509 3rd Qu.:0.1674 3rd Qu.:0.1517 3rd Qu.:-0.0723
#> Max. :0.2339 Max. :0.4326 Max. :0.3677 Max. :-0.0022
#> NA's :1554 NA's :686 NA's :1736 NA's :882In 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_{si}\) is the travel time and \(cost_{si}\) 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}\] Where \(\beta_{tt}^r\) are random draws 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, then define the type, name and number of draws used, and we construct the random coefficient \(\beta_{tt}\). 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 significantly more demanding than models without mixing. Furthermore, using both inter and intra-individual requires large amounts of memory, that can further slow the estimation process.
# ####################################################### #
#### 1. Definition of core settings
# ####################################################### #
### Clear memory
rm(list = ls())
### Load libraries
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
)
# ####################################################### #
#### 2. Data loading ####
# ####################################################### #
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.0000,
asc_bus =-2.4948,
asc_air =-1.1510,
asc_rail =-0.7153,
mu_tt =-4.4104,
sigma_tt = 0.4637,
b_c =-0.0613)
### 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 = 200,
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()
#> Missing setting for workInLogs, set to default of FALSE
#> Missing setting for seed, set to default of 13
#> Missing setting for HB, set to default of FALSE
#> Several observations per individual detected based on the value of ID.
#> Setting panelData set to TRUE.
#> All checks on apollo_control completed.
#> All checks on data completed.
#> Generating inter draws . Done
# ####################################################### #
#### 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)
#> Testing probability function (apollo_probabilities)
#>
#> All checks passed for MNL model component
#> Overview of choices for MNL model component:
#> car bus air rail
#> Times available 5446.00 6314.00 5264.00 6118.00
#> Times chosen 1946.00 358.00 1522.00 3174.00
#> Percentage chosen overall 27.80 5.11 21.74 45.34
#> Percentage chosen when available 35.73 5.67 28.91 51.88
#>
#> Attempting to split data into 2 pieces.
#> Number of observations per worker (thread):
#> worker_1 worker_2
#> 3500 3500
#> 87.7Mb of RAM in use before splitting.
#> Splitting draws.. Done. 98.3Mb of RAM in use.
#> Splitting database.. Done. 99.2Mb of RAM in use.
#> Creating workers and loading libraries... Done. 227.7Mb of RAM in use.
#> Copying data to workers... Done. 227.8Mb of RAM in use (max was 239.3Mb)
#>
#>
#> Starting main estimation
#> Initial function value: -5518.018
#> Initial gradient value:
#> asc_bus asc_air asc_rail mu_tt sigma_tt
#> -0.105195795 0.132730747 -0.010276381 0.440247277 0.008943061
#> b_c
#> 16.505906387
#> initial value 5518.017700
#> iter 2 value 5518.017599
#> iter 2 value 5518.017598
#> iter 2 value 5518.017548
#> final value 5518.017548
#> converged
#>
#> Estimated values:
#> [,1]
#> asc_car 0.0000
#> asc_bus -2.4948
#> asc_air -1.1510
#> asc_rail -0.7153
#> mu_tt -4.4104
#> sigma_tt 0.4637
#> b_c -0.0613
#>
#> Computing covariance matrix using numDeriv package.
#> (this may take a while)
#> 0%....25%....50%....75%...100%
#> Hessian calculated with numDeriv will be used.
#> Calculating LL(0)... -8196.02
#> Updating inputs... Done.
#> Calculating LL of each model component...Done.
apollo_modelOutput(model)
#> Model run using Apollo for R, version 0.0.6
#> www.apollochoicemodelling.com
#>
#> Model name : MMNL
#> Model description : Simple MMNL model on mode choice SP data
#> Model run at : 2019-03-13 17:13:40
#> Estimation method : bfgs
#> Model diagnosis : successful convergence
#> Number of individuals : 500
#> Number of observations : 7000
#> Estimated parameters : 6
#> Number of inter-person draws : 200 (halton)
#>
#> LL(start) : -5518.018
#> LL(0) : -8196.021
#> LL(final) : -5518.018
#> Rho-square (0) : 0.3267
#> Adj.Rho-square (0) : 0.326
#> AIC : 11048.04
#> BIC : 11089.16
#> Time taken (hh:mm:ss) : 00:05:56.71
#> Iterations : 4
#> Number of cores used : 2
#>
#> Estimates:
#> Estimate Std.err. t.ratio(0) Rob.std.err. Rob.t.ratio(0)
#> asc_car 0.0000 NA NA NA NA
#> asc_bus -2.4948 0.0763 -32.68 0.0805 -31.01
#> asc_air -1.1510 0.1353 -8.51 0.1376 -8.36
#> asc_rail -0.7153 0.0960 -7.45 0.1006 -7.11
#> mu_tt -4.4104 0.0561 -78.68 0.0538 -82.01
#> sigma_tt 0.4637 0.0296 15.65 0.0296 15.65
#> b_c -0.0613 0.0016 -38.35 0.0019 -32.13
#>
#>
#> Overview of choices for MNL model component:
#> car bus air rail
#> Times available 5446.00 6314.00 5264.00 6118.00
#> Times chosen 1946.00 358.00 1522.00 3174.00
#> Percentage chosen overall 27.80 5.11 21.74 45.34
#> Percentage chosen when available 35.73 5.67 28.91 51.88
#>
apollo_saveOutput(model)
#> Estimates saved to MMNL_estimates.csv
#> Classical covariance matrix saved to MMNL_covar.csv
#> Robust covariance matrix saved to MMNL_robcovar.csv
#> Classical correlation matrix saved to MMNL_covar.csv
#> Robust correlation matrix saved to MMNL_robcorr.csv
#> Model object saved to MMNL.rds
# ####################################################### #
#### 7. Postprocessing of results ####
# ####################################################### #
### Use the estimated model to make predictions
predictions_base = apollo_prediction(model,
apollo_probabilities,
apollo_inputs)
#> Updating inputs...Done.
#> Running predictions from model... Done.
### 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)
#> Updating inputs...Done.
#> Running predictions from model... Done.
### 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)
#> car bus air rail
#> Min. :0.0000 Min. :0.0000 Min. :0.0000 Min. :-0.3454
#> 1st Qu.:0.0768 1st Qu.:0.0724 1st Qu.:0.0701 1st Qu.:-0.2257
#> Median :0.1216 Median :0.1213 Median :0.1327 Median :-0.1480
#> Mean :0.1131 Mean :0.1246 Mean :0.1361 Mean :-0.1553
#> 3rd Qu.:0.1594 3rd Qu.:0.1679 3rd Qu.:0.1962 3rd Qu.:-0.0762
#> Max. :0.2338 Max. :0.4307 Max. :0.4586 Max. :-0.0026
#> NA's :1554 NA's :686 NA's :1736 NA's :882