| Title: | Tools for Choice Model Estimation and Application |
|---|---|
| Description: | Choice models are a widely used technique across numerous scientific disciplines. The Apollo package is a very flexible tool for the estimation and application of choice models in R. Users are able to write their own model functions or use a mix of already available ones. Random heterogeneity, both continuous and discrete and at the level of individuals and choices, can be incorporated for all models. There is support for both standalone models and hybrid model structures. Both classical and Bayesian estimation is available, and multiple discrete continuous models are covered in addition to discrete choice. Multi-threading processing is supported for estimation and a large number of pre and post-estimation routines, including for computing posterior (individual-level) distributions are available. For examples, a manual, and a support forum, visit <http://www.ApolloChoiceModelling.com>. For more information on choice models see Train, K. (2009) <isbn:978-0-521-74738-7> and Hess, S. & Daly, A.J. (2014) <isbn:978-1-781-00314-5> for an overview of the field. |
| Authors: | Stephane Hess [aut, cre], David Palma [aut], Thomas Hancock [ctb] |
| Maintainer: | Stephane Hess <[email protected]> |
| License: | GPL-2 |
| Version: | 0.3.4 |
| Built: | 2024-10-02 05:26:46 UTC |
| Source: | CRAN |
This function is only called by R when attaching the package.
.onAttach(libname, pkgname).onAttach(libname, pkgname)
libname |
Name of library. |
pkgname |
Name of package. |
Nothing
Receives an estimated model object, calculates its Hessian, and classical and robust covariance matrix, and returns the same model object, but with these additional elements.
apollo_addCovariance(model, apollo_inputs)apollo_addCovariance(model, apollo_inputs)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
model.
Attaches parameters and data to allow users to refer to individual variables by name without reference to the object that contains them.
apollo_attach(apollo_beta, apollo_inputs)apollo_attach(apollo_beta, apollo_inputs)
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
This function should be called at the beginning of apollo_probabilities
to make writing the log-likelihood more user-friendly. If used, then apollo_detach
should be called at the end of apollo_probabilities, or more conveniently,
using on.exit after the initial call to apollo_attach.
apollo_attach attaches apollo_beta, database, draws,
and the output of apollo_randCoeff and apollo_lcPars, if they are
defined by the user.
Nothing.
Averages individual-specific likelihood across inter-individual draws.
apollo_avgInterDraws(P, apollo_inputs, functionality)apollo_avgInterDraws(P, apollo_inputs, functionality)
P |
List of vectors, matrices or 3-dim arrays. Likelihood of the model components. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
Argument P with (for most functionalities) the original contents averaged over inter-individual draws. Shape depends on argument functionality.
"components": Returns P without changes.
"conditionals": Returns P without averaging across draws. Drops all components except "model".
"estimate": Returns P containing the likelihood of the model averaged across inter-individual draws. Drops all components except "model".
"gradient": Returns P containing the gradient of the likelihood averaged across inter-individual draws. Drops all components except "model".
"output": Returns P containing the likelihood of all model components averaged across inter-individual draws.
"prediction": Returns P containing the probabilities/likelihoods of all alternatives for all model components averaged across inter-individual draws.
"preprocess": Returns P without changes.
"raw": Returns P without changes.
"report": Returns P without changes.
"shares_LL": Returns P without changes.
"validate": Returns P containing the likelihood of the model averaged across inter-individual draws. Drops all components except "model".
"zero_LL": Returns P without changes.
Averages observation-specific likelihood across intra-individual draws.
apollo_avgIntraDraws(P, apollo_inputs, functionality)apollo_avgIntraDraws(P, apollo_inputs, functionality)
P |
List of vectors, matrices or 3-dim arrays. Likelihood of the model components. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
Argument P with (for most functionalities) the original contents averaged over intra-individual draws. Shape depends on argument functionality.
"components": Returns P without changes.
"conditionals": Returns P containing the likelihood of the model averaged across intra-individual draws. Drops all components except for "model".
"estimate": Returns P containing the likelihood of the model averaged across intra-individual draws. Drops all components except "model".
"gradient": Returns P containing the gradient of the likelihood averaged across intra-individual draws. Drops all components except "model".
"output": Returns P containing the likelihood of all model components averaged across intra-individual draws.
"prediction": Returns P containing the probabilities of all alternatives for all model components averaged across intra-individual draws.
"preprocess": Returns P without changes.
"raw": Returns P without changes.
"report": Returns P without changes.
"validate": Returns P containing the likelihood of the model averaged across intra-individual draws. Drops all components but "model".
"zero_LL": Returns P without changes.
Carries out the Ben-Akiva & Swait test for non-nested models and reports the corresponding p-value.
apollo_basTest(model1, model2)apollo_basTest(model1, model2)
model1 |
Either a character variable with the name (and possibly path) of a previously estimated model, or an estimated model in memory, as returned by apollo_estimate. |
model2 |
Either a character variable with the name (and possibly path) of a previously estimated model, or an estimated model in memory, as returned by apollo_estimate. |
The two models need to both be discrete choice, and need to have been estimated on the same data.
Ben-Akiva & Swait test p-value (invisibly)
Samples individuals with replacement from the database, and estimates the model for each sample.
apollo_bootstrap( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, estimate_settings = list(estimationRoutine = "bgw", maxIterations = 200, writeIter = FALSE, hessianRoutine = "none", printLevel = 2L, silent = FALSE, maxLik_settings = list()), bootstrap_settings = list(nRep = 30, samples = NA, calledByEstimate = FALSE, recycle = TRUE) )apollo_bootstrap( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, estimate_settings = list(estimationRoutine = "bgw", maxIterations = 200, writeIter = FALSE, hessianRoutine = "none", printLevel = 2L, silent = FALSE, maxLik_settings = list()), bootstrap_settings = list(nRep = 30, samples = NA, calledByEstimate = FALSE, recycle = TRUE) )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
estimate_settings |
List. Options controlling the estimation process. See apollo_estimate.
|
bootstrap_settings |
List containing settings for the sampling procedure. User input is required for all settings except those with a default or marked as optional.
|
This function implements a basic block bootstrap. It estimates the model parameters on nRep different samples.
Each new sample is constructed by sampling with replacement from the original full sample. Each new sample has as many
individuals as the original sample, though some of them may be repeated. Sampling is done at the individual level,
therefore if different individuals have different number of observations, each re-sample does not necessarily have the same number of observations.
If the sampling should be done at the individual level (not recommended for panel data), then the optional
bootstrap_settings$samples argument should be provided.
For each sample, only the parameters and log-likelihood are estimated. Standard errors are not calculated (they may be added in future versions). The composition of the re-samples is stored in a file, but is stable with the same seed.
This function writes three different files to the working or output directory:
modelName_bootstrap_params.csv: estimated parameters, final log-likelihood, and number of observations for each re-sample
modelName_bootstrap_samples.csv: composition of each re-sample.
modelName_bootstrap_vcov.csv: variance-covariance matrix of the estimated parameters across re-samples.
The first two files are updated throughout the run of this function, while the last one is only written once the function finishes.
When run, this function will look for the first two files above in the working/output directory. If they are found, the function will attempt to pick up re-sampling from where those files left off. This is useful in cases where the original bootstrapping was interrupted, or when additional re-sampling runs are to be performed.
List with three elements.
estimates: Matrix containing the parameter estimates for each repetition. As many rows as repetitions and as many columns as parameters.
LL: Vector of final log-likelihoods of each repetition.
varcov: Covariance matrix of the estimated parameters across the repetitions.
This function also writes three output files to the working/output directory, with the following names ('x' represents the model name):
x_bootstrap_params.csv: Table containing the parameter estimates, log-likelihood, and number of observations for each repetition.
x_bootstrap_samples.csv: Table containing the description of the sample used in each repetition. Same format than bootstrap_settings$samples.
x_bootstrap_vcov: Table containing the covariance matrix of estimated parameters across the repetitions.
Checks that the user-defined functions used by Apollo are correctly defined by the user.
apollo_checkArguments( apollo_probabilities = NA, apollo_randCoeff = NA, apollo_lcPars = NA )apollo_checkArguments( apollo_probabilities = NA, apollo_randCoeff = NA, apollo_lcPars = NA )
apollo_probabilities |
Function. Likelihood function as defined by the user. |
apollo_randCoeff |
Function. Used with mixing models. Constructs the random parameters of a mixing model. Receives two arguments:
|
apollo_lcPars |
Function. Used with latent class models. Constructs a list of parameters for each latent class. Receives two arguments:
|
It only checks that the functions have the correct definition of inputs. It does not run the functions.
Returns (invisibly) TRUE if definitions are correct, and FALSE otherwise.
Compares market shares across subsamples in dataset, and conducts statistical tests.
apollo_choiceAnalysis(choiceAnalysis_settings, apollo_control, database)apollo_choiceAnalysis(choiceAnalysis_settings, apollo_control, database)
choiceAnalysis_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
apollo_control |
List. Options controlling the running of the code. See apollo_validateInputs. |
database |
data.frame. Data used by model. |
Saves the output to a csv file in the working/output directory.
Silently returns a matrix containing the mean value for each explanator for those cases where an alternative is chosen and where it is not chosen,
as well as the t-test comparing those means (H0: equivalence).
The table is also written to a file called modelName_choiceAnalysis.csv and printed to screen.
Calculates class allocation probabilities for a Latent Class model using a Multinomial Logit model and can also perform other operations based on the value of the functionality argument.
apollo_classAlloc(classAlloc_settings)apollo_classAlloc(classAlloc_settings)
classAlloc_settings |
List of inputs of the MNL model. It should contain the following.
|
The returned object depends on the value of argument functionality, which it fetches from the calling stack (see apollo_validateInputs).
"components": Same as "estimate".
"conditionals": Same as "estimate".
"estimate": List of vector/matrices/arrays with the allocation probabilities for each class.
"gradient": List containing the likelihood and gradient of the model component.
"output": Same as "estimate".
"prediction": Same as "estimate".
"preprocess": Returns a list with pre-processed inputs, based on classAlloc_settings.
"raw": Same as "estimate".
"report": Same as "estimate".
"shares_LL": List with probabilities for each class in an equal shares setting.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"zero_LL": List with probabilities for each class in an equal shares setting.
Calculates the probabilities of a Cross-nested Logit model and can also perform other operations based on the value of the functionality argument.
apollo_cnl(cnl_settings, functionality)apollo_cnl(cnl_settings, functionality)
cnl_settings |
List of inputs of the CNL model. User input is required for all settings except those with a default or marked as optional.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
For the model to be consistent with utility maximisation, the estimated value of the lambda parameter of all nests
should be between 0 and 1. Lambda parameters are inversely proportional to the correlation between the error terms of
alternatives in a nest. If lambda=1, there is no relevant correlation between the unobserved
utility of alternatives in that nest.
Alpha parameters inside cnlStructure should be between 0 and 1. Using a transformation to ensure
this constraint is satisfied is recommended for complex structures (e.g. logistic transformation).
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 cnl_settings.
"raw": Same as "prediction".
"report": List with tree structure and choice overview.
"shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.
"validate": Same as "estimate".
"zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.
Combines model components to create likelihood for overall model.
apollo_combineModels( P, apollo_inputs, functionality, components = NULL, asList = TRUE )apollo_combineModels( P, apollo_inputs, functionality, components = NULL, asList = TRUE )
P |
List of vectors, matrices or 3-dim arrays. Likelihood of the model components. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
components |
Character vector. Optional argument. Names of elements in P that should be multiplied to construct the whole model likelihood. If a single element is provided, it is interpreted as a regular expression. Default is to include all components in P. |
asList |
Logical. Only used if |
This function should be called inside apollo_probabilities after all model components have been produced.
It should be called before apollo_avgInterDraws, apollo_avgIntraDraws, apollo_panelProd and apollo_prepareProb, whichever apply, except where these functions are called inside any latent class components of the overall model.
Argument P with (for most functionalities) an extra element called "model", which is the product of all the other elements. Shape depends on argument functionality.
"components": Returns P without changes.
"conditionals": Returns P with an extra component called "model", which is the product of all other elements of P.
"estimate": Returns P with an extra component called "model", which is the product of all other elements of P.
"gradient": Returns P containing the gradient of the likelihood after applying the product rule across model components.
"output": Returns P with an extra component called "model", which is the product of all other elements of P.
"prediction": Returns P without changes.
"preprocess": Returns P without changes.
"raw": Returns P without changes.
"shares_LL": Returns P with an extra component called "model", which is the product of all other elements of P.
"validate": Returns P with an extra component called "model", which is the product of all other elements of P.
"zero_LL": Returns P with an extra component called "model", which is the product of all other elements of P.
Writes results from various models to a single csv file.
apollo_combineResults(combineResults_settings = NULL)apollo_combineResults(combineResults_settings = NULL)
combineResults_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
Nothing, but writes a file called 'model_comparison_[date].csv' in the working/output directory.
Compares the content of apollo_inputs to their counterparts in the global environment
apollo_compareInputs(apollo_inputs)apollo_compareInputs(apollo_inputs)
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
Logical. TRUE if the content of apollo_inputs is the same than the one in the global environment, FALSE otherwise.
Calculates posterior expected values (conditionals) of random coefficient models (continuous or discrete mixtures/latent class)
apollo_conditionals(model, apollo_probabilities, apollo_inputs)apollo_conditionals(model, apollo_probabilities, apollo_inputs)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
This functions is only meant for use with models using either continuous distributions or latent classes, not both at the same time
Depends on whether the model uses continuous mixtures or latent class.
If the model contains a continuous mixture, the function returns a list of matrices. Each matrix has dimensions nIndiv x 3. One matrix per random component. Each row of each matrix contains the indivID of an individual, and the posterior mean and s.d. of this random component for this individual.
If the model contains latent classes, the function returns a matrix with the posterior class allocation probabilities for each individual.
If the model contains both continuous mixtures and latent classes, the function fails.
Applies the Delta method to calculate the standard errors of transformations of parameters.
apollo_deltaMethod(model, deltaMethod_settings)apollo_deltaMethod(model, deltaMethod_settings)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
deltaMethod_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
apollo_deltaMethod can be used in two ways. The first and recommended way is to provide an
element called expression inside its argument deltaMethod_settings. expression
should contain the expression or expressions for which the standard error is/are to be calculated, as text. For
example, to calculate the ratio between parameters b1 and b2, expression=c(vtt="b1/b2") should be used.
The second method is to provide the name of a specific operation inside deltaMethod_settings.
The following five operations are supported.
sum: Calculates the s.e. of parName1 + parName2
diff: Calculates the s.e. of parName1 - parName2 and parName2 - parName1
prod: Calculates the s.e. of parName1*parName2
ratio: Calculates the s.e. of parName1/parName2 and parName2/parName1
exp: Calculates the s.e. of exp(parName1)
logistic: If only parName1 is provided, it calculates the s.e. of
exp(parName1)/(1+exp(parName1)) and 1/(1+exp(parName1)).
If parName1 and parName2 are provided, it calculates
exp(par_i)/(1+exp(parName1)+exp(parName2)) for i=1, 2, and 3 (par_3 = 1).
lognormal: Calculates the mean and s.d. of a lognormal distribution based on the mean
(parName1) and s.d. (parName2) of the underlying normal.
By default, apollo_deltaMethod uses the robust covariance matrix. However, the user can change this through the varcov setting.
Matrix containing value, s.e. and t-ratio resulting from the requested expression or operation. This is also printed to screen.
Detaches variables attached by apollo_attach.
apollo_detach(apollo_beta = NA, apollo_inputs = NA)apollo_detach(apollo_beta = NA, apollo_inputs = NA)
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
This function detaches the variables attached by apollo_attach.
It should be called at the end of apollo_probabilities, only if
apollo_attach was called and the beginning. This can also be achieved
by adding the line on.exit(apollo_detach(apollo_beta, apollo_inputs))
right after calling apollo_attach.
This function can also be called without any arguments, i.e. apollo_detach().
Nothing.
Calculate probabilities of a Decision Field Theory (DFT) model and can also perform other operations based on the value of the functionality argument.
apollo_dft(dft_settings, functionality)apollo_dft(dft_settings, functionality)
dft_settings |
List of settings for the DFT model. It should contain the following elements.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
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.
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
Pre-process input for common models return
apollo_diagnostics(inputs, modelType, apollo_inputs, data = TRUE, param = TRUE)apollo_diagnostics(inputs, modelType, apollo_inputs, data = TRUE, param = TRUE)
inputs |
List of settings |
modelType |
Character. Type of model, e.g. "mnl", "nl", "cnl", etc. |
apollo_inputs |
List of main inputs to the model estimation process. See apollo_validateInputs. |
data |
Boolean. TRUE for printing report related to dependent and independent variables. FALSE for not printing it. Default is TRUE. |
param |
Boolean. TRUE for printing report related to estimated parameters (e.g. model structure). FALSE for not printing it. Default is TRUE. |
(invisibly) TRUE if no error happend during execution.
A simulated dataset containing 10,000 stated medication choices among four alternatives.
apollo_drugChoiceDataapollo_drugChoiceData
A data.frame with 10,000 rows and 33 variables:
Numeric. Identification number of the individual.
Numeric. Index of choice situations for each individual, going from 1 to 10.
Numeric. Index of alternative selected as best option.
Numeric. Index of alternative selected as second-best option.
Numeric. Index of alternative selected as third-best option.
Numeric. Index of alternative selected as worst option.
Character. Brand for alternative 1.
Character. Country of origin for alternative 1.
Character. Characteristics of alternative 1 (standard, fast acting, or double strength).
Numeric. Chance of suffering negative side effects with alternative 1 (out of 100,000).
Numeric. Cost of alternative 1 in Pounds sterling (GBP).
Character. Brand for alternative 2.
Character. Country of origin for alternative 2.
Character. Characteristics of alternative 2 (standard, fast acting, or double strength).
Numeric. Chance of suffering negative side effects with alternative 2 (out of 100,000).
Numeric. Cost of alternative 2 in Pounds sterling (GBP).
Character. Brand for alternative 3.
Character. Country of origin for alternative 3.
Character. Characteristics of alternative 3 (standard, fast acting, or double strength).
Numeric. Chance of suffering negative side effects with alternative 3 (out of 100,000).
Numeric. Cost of alternative 3 in Pounds sterling (GBP).
Character. Brand for alternative 4.
Character. Country of origin for alternative 4.
Character. Characteristics of alternative 4 (standard, fast acting, or double strength).
Numeric. Chance of suffering negative side effects with alternative 4 (out of 100,000).
Numeric. Cost of alternative 4 in Pounds sterling (GBP).
Numeric. 1 if the respondent is a regular user of headache medicine, 0 otherwise.
Numeric. 1 if the respondent holds a university degree, 0 otherwise.
Numeric. 1 if the respondent is 50 years old or older, 0 otherwise.
Numeric. Level of agreement from 1 (strongly disagree) to 5 (strongly agree) with the phrase 'I am concerned about the quality of drugs developed by unknown companies'.
Numeric. Level of agreement from 1 (strongly disagree) to 5 (strongly agree) with the phrase 'I believe that ingredients are the same no matter what brand'.
Numeric. Level of agreement from 1 (strongly disagree) to 5 (strongly agree) with the phrase 'The original patent holders have valuable experience with their medicines'.
Numeric. Level of agreement from 1 (strongly disagree) to 5 (strongly agree) with the phrase 'I believe the dominance of big pharmaceutical companies is unhelpful'.
This dataset is to be used for discrete choice modelling. Data comes from 1,000 individuals, each with ten stated choice (SC) scenarios involving a choice among headache medication. There are 10,000 choices in total. Data is simulated. Each observation contains attributes of the alternatives, characteristics of the respondent, and their answers to four attitudinal questions. All four alternatives are always available for all individuals. Alternatives 1 and 2 are branded, while alternatives 3 and 4 are generic. Respondents provide a full ranking of alternatives for each choice task (i.e. observation).
http://www.apollochoicemodelling.com/
Calculates gradients (derivatives) of utility functions.
apollo_dVdB(apollo_beta, apollo_inputs, V)apollo_dVdB(apollo_beta, apollo_inputs, V)
apollo_beta |
Named numeric vector of parameters. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
V |
List of functions |
Named list. Each element is itself a list of functions: the partial derivatives of the elements of V.
Calculates gradients (derivatives) of utility functions.
apollo_dVdBOld(apollo_beta, apollo_inputs, V)apollo_dVdBOld(apollo_beta, apollo_inputs, V)
apollo_beta |
Named numeric vector of parameters. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
V |
List of functions |
Named list. Each element is a function that returns a list, where each element is the partial derivatives of the elements of V.
Calculates the probabilities of an Exploded Logit model and can also perform other operations based on the value of the functionality argument.
apollo_el(el_settings, functionality)apollo_el(el_settings, functionality)
el_settings |
List of inputs of the Exploded Logit model. It shoud contain the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
The function calculates the probability of a ranking as a product of Multinomial Logit models with gradually reducing availability, where scale differences can be allowed for.
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": List containing the likelihood and gradient of the model component.
"output": Same as "estimate" but also writes summary of input data to internal Apollo log.
"prediction": Not applicable (NA).
"preprocess": Returns a list with pre-processed inputs, based on el_settings.
"raw": Same as "estimate"
"report": Choice overview across stages.
"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.
Calculates the likelihood function of the MDC model with exogenous budget. Can also predict and validate inputs.
apollo_emdc(emdc_settings, functionality = "estimate")apollo_emdc(emdc_settings, functionality = "estimate")
emdc_settings |
List of settings for the model. It includes the following.
|
functionality |
Character. Either "validate", "zero_LL", "estimate", "conditionals", "raw", "output" or "prediction" |
This model extends the traditional multiple discrete-continuous (MDC) framework by (i) making the marginal utility of the outside good deterministic, and (ii) including complementarity and substitution in the model formulation. See the following working paper for more details:
Palma, D. & Hess, S. (2022) Extending the Multiple Discrete Continuous (MDC) modelling framework to consider complementarity, substitution, and an unobserved budget. Transportation Reserarch 161B, 13 - 35. https://doi.org/10.1016/j.trb.2022.04.005
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 probability of the chosen alternative.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"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"
Calculates the likelihood function of the MDC model with exogenous budget. Can also predict and validate inputs.
apollo_emdc1(emdc_settings, functionality = "estimate")apollo_emdc1(emdc_settings, functionality = "estimate")
emdc_settings |
List of settings for the model. It includes the following.
|
functionality |
Character. Either "validate", "zero_LL", "estimate", "conditionals", "raw", "output" or "prediction" |
This model extends the traditional multiple discrete-continuous (MDC) framework by (i) making the marginal utility of the outside good deterministic, and (ii) including complementarity and substitution in the model formulation. See the following working paper for more details:
Palma, D. & Hess, S. (2022) Extending the Multiple Discrete Continuous (MDC) modelling framework to consider complementarity, substitution, and an unobserved budget. Transportation Reserarch 161B, 13 - 35. https://doi.org/10.1016/j.trb.2022.04.005
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 probability of the chosen alternative.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"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"
Calculates the likelihood function of the extended MDC model. Can also predict and validate inputs.
apollo_emdc2(emdc_settings, functionality = "estimate")apollo_emdc2(emdc_settings, functionality = "estimate")
emdc_settings |
List of settings for the model. It includes the following.
|
functionality |
Character. Either "validate", "zero_LL", "estimate", "conditionals", "raw", "output" or "prediction" |
This model extends the traditional multiple discrete-continuous (MDC) framework by (i) dropping the need to define a budget, (ii) making the marginal utility of the outside good deterministic, and (iii) including complementarity and substitution in the model formulation. See the following working paper for more details:
Palma, D. & Hess, S. (Working Paper) Some adaptations of Multiple Discrete-Continuous Extreme Value (MDCEV) models for a computationally tractable treatment of complementarity and substitution effects, and reduced influence of budget assumptions
Avilable at: http://stephanehess.me.uk/publications.html
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 probability of the chosen alternative.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"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"
Estimates a model using the likelihood function defined by apollo_probabilities.
apollo_estimate( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, estimate_settings = NA )apollo_estimate( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, estimate_settings = NA )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
estimate_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
This is the main function of the Apollo package. The estimation process begins by running a number of checks on the
apollo_probabilities function provided by the user.
If all checks are passed, estimation begins. There is no limit to estimation time other than reaching the maximum number of
iterations. If Bayesian estimation is used, estimation will finish once the predefined number of iterations are completed.
By default, this functions writes the estimated parameter values in each iteration to a file in the working/output directory. Writing
can be turned off by setting estimate_settings$writeIter to FALSE.
By default, final results are not written into a file nor printed to the console, so users must make sure
to call function apollo_modelOutput and/or apollo_saveOutput afterwards.
Users are strongly encouraged to visit http://www.apollochoicemodelling.com/ to download examples on how to use the Apollo package.
The webpage also provides a detailed manual for the package, as well as a user-group to get further help.
model object
Estimates a model using Bayesian estimation on the likelihood function defined by apollo_probabilities.
apollo_estimateHB( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, estimate_settings = NA )apollo_estimateHB( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, estimate_settings = NA )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
estimate_settings |
List. Options controlling the estimation process, as used for in apollo_estimate. |
This is a sub function of apollo_estimate which is called when using Bayesian estimation.
model object
Expands loops replacing the index by its value. It also evaluates paste and paste0, and removes get.
apollo_expandLoop(f, apollo_inputs, validate = TRUE)apollo_expandLoop(f, apollo_inputs, validate = TRUE)
f |
function (usually |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
validate |
Logical. If TRUE, the new function will be validated before being returned |
For example, the expression
for(j in 1:3) V[[paste0('alt',j)]] = b1*get(paste0('x',j)) + b2*X[,j]
would be expanded into:
V[[alt1]] = b1*x1 + b2*X[,1]
V[[alt2]] = b1*x2 + b2*X[,2]
V[[alt3]] = b1*x3 + b2*X[,3]
A function or an expression (same type as input f)
Given a multi-row input, keeps only the first row for each individual.
apollo_firstRow(P, apollo_inputs)apollo_firstRow(P, apollo_inputs)
P |
List of vectors, matrices or 3-dim arrays. Likelihood of the model components (or other object). |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
This a function to keep only the first row of an object per indidividual. It can handle multiple types of components, including scalars, vectors and three-dimensional arrays (cubes). The argument database MUST contain a column called 'apollo_sequence', which is created by apollo_validateData.
If P is a list, then it returns a list where each element has only the first row of each individual.
If P is a single element, then it returns a single element with only the first row of each individual.
The size of the element is changed only in the first dimension. If input is a scalar, then it returns a vector with the element repeated as many
times as individuals in database. If the element is a vector, its length will be changed to the number of individuals. If the element is
a matrix, then its first dimension will be changed to the number of individuals, while keeping the size of the second dimension. If the element
is a cube, then only the first dimension's length is changed, preserving the others.
Given the estimates of a model, it compares the log-likelihood at the observation level across categories of observations.
apollo_fitsTest(model, apollo_probabilities, apollo_inputs, fitsTest_settings)apollo_fitsTest(model, apollo_probabilities, apollo_inputs, fitsTest_settings)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
fitsTest_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
Prints a table comparing the average log-likelihood at the observation level for each category.
Matrix with average log-likelihood at observation level per category (invisibly).
Calculates the probabilities of a Fractional Multinomial Logit model and can also perform other operations based on the value of the functionality argument.
apollo_fmnl(fmnl_settings, functionality)apollo_fmnl(fmnl_settings, functionality)
fmnl_settings |
List of inputs of the FMNL model. It should contain the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
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": List containing the likelihood and gradient of the model component.
"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 probability of the chosen alternative.
"preprocess": Returns a list with pre-processed inputs, based on fmnl_settings.
"raw": Same as "prediction"
"report": Overview of dependent variable
"shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.
Calculates the probabilities of a Fractional Nested Logit (FNL) model and can also perform other operations based on the value of the functionality argument.
apollo_fnl(fnl_settings, functionality)apollo_fnl(fnl_settings, functionality)
fnl_settings |
List of inputs of the FNL model. It should contain the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
In this implementation of the Nested Logit model, each nest must have a lambda parameter associated to it.
For the model to be consistent with utility maximisation, the estimated value of the Lambda parameter of all nests
should be between 0 and 1. Lambda parameters are inversely proportional to the correlation between the error terms of
alternatives in a nest. If lambda=1, then there is no relevant correlation between the unobserved
utility of alternatives in that nest.
The tree must contain an upper nest called "root". The lambda parameter of the root is automatically
set to 1 if not specified in nlNests, but can be changed by the user if desired (though not advised).
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 probability of the chosen alternative.
"preprocess": Returns a list with pre-processed inputs, based on fnl_settings.
"raw": Same as "prediction"
"report": List with tree structure and choice overview.
"shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.
Prepares environment (the global environment if called by the user) for model definition and estimation.
apollo_initialise()apollo_initialise()
This function detaches variables and makes sure that output is directed to console. It does not delete variables from the working environment.
Nothing.
Adds componentName2 to model calls
apollo_insertComponentName(e)apollo_insertComponentName(e)
e |
An expression or a function. It will usually be apollo_probabilities. |
The original argument 'e' but modified to incorporate a new setting called 'componentName2' to every call to apollo_<model> (e.g. apollo_mnl, apollo_nl, etc.).
Takes a likelihood function and inserts function () before key elements to allow for analytic gradient calculation
apollo_insertFunc(f, like = TRUE, randCoeff = FALSE, lcPars = FALSE)apollo_insertFunc(f, like = TRUE, randCoeff = FALSE, lcPars = FALSE)
f |
Function. Expressions inside it will be turned into functions. Usually |
like |
Logical. Must be TRUE if |
randCoeff |
Logical. Must be TRUE if |
lcPars |
Logical. Must be TRUE if |
It modifies the definition of the following models.
apollo_mnl: Turns all elements inside mnl_settings$V into functions.
apollo_ol: Turns ol_settings$V and all elements inside ol_settings$tau into functions.
apollo_op: Turns op_settings$V and all elements inside op_settings$tau into functions.
apollo_normalDensity: Turns normalDensity_settings$xNormal, normalDensity_settings$mu and normalDensity_settings$sigma into functions.
It can only track a maximum of 3 levels of depth in definitions. For example:
V <- list()
V[["A"]] <- b1*x1A + b2*x2A
V[["B"]] <- b1*x1B + b2*x2B
mnl_settings1 <- list(alternatives=c("A", "B"), V = V, choiceVar= Y, avail = 1, componentName="MNL1")
P[["MNL1"]] <- apollo_mnl(mnl_settings1, functionality)
But it may not be able to deal with the following:
VA <- b1*x1A + b2*x2A
V <- list()
V[["A"]] <- VA
V[["B"]] <- b1*x1B + b2*x2B
mnl_settings1 <- list(alternatives=c("A", "B"), V = V, choiceVar= Y, avail = 1, componentName="MNL1")
P[["MNL1"]] <- apollo_mnl(mnl_settings1, functionality)
But that might be enough given how apollo_dVdB works.
Function f but with relevant expressions turned into function definitions.
tau=c(...) by tau=list(...) in calls to apollo_ol
Takes a function, looks for calls to apollo_ol, identifies the corresponding
ol_settings, then goes inside the definition of ol_settings and replaces
tau=c(...) for tau=list(...).
apollo_insertOLList(f)apollo_insertOLList(f)
f |
Function. Usually |
This only goes one level deep in definitions. For example, it will work
correctly in the following cases:
ol_settings = list(outcomeOrdered = y1,
V = b1*x1,
tau = c(tau11, tau12))
P[["OL1"]] = apollo_ol(ol_settings, functionality)
P[["OL2"]] = apollo_ol(list(outcomeOrdered=y2, V=b2*x2, tau=c(tau21, tau22)),
functionality)
But it will not work on the following cases:
Tau = c(tau1, tau2, tau3)
ol_settings = list(outcomeOrdered = y2,
V = b2*x2,
tau = Tau)
P[["OL1"]] = apollo_ol(ol_settings, functionality)
P[["OL2"]] = apollo_ol(list(outcomeOrdered=y1, V=b1*x1, tau=Tau), functionality)
This function is called by apollo_modifyUserDefFunc to allow for analytical gradients when using apollo_ol.
Function f with tau=c(...) replaced by
tau=list(...).
Given a numeric object (scalar, vector, matrix or 3-dim array) inserts rows in the specified places.
apollo_insertRows(v, r, val)apollo_insertRows(v, r, val)
v |
Numeric scalar, vector, matrix or 3-dim array. |
r |
Boolean vector. TRUE for inserting a row from |
val |
Numeric scalar. Value that will fill new rows. |
In general, r should be longer than the number of rows in utilities, and sum(r)=nrow(v).
If not, then a new object with as many rows as r will be returned. Old rows will be taken
from utilities from the top down.
The same argument v but with rows added where r==FALSE.
Takes a function, looks for the definition of relevant parts of rrm_settings, and introduces quotes on them. This is to facilitate their processing by apollo_rrm under functionality="preprocessing".
apollo_insertRRMQuotes(f)apollo_insertRRMQuotes(f)
f |
Function. Usually |
Function f with relevant expressions turned into character.
It changes the syntax of the function by replacing variable names for their scaled form, e.g. x –> x*apollo_inputs$apollo_scale[["x"]]. In assignments, it only scales the right side of the assignment.
apollo_insertScaling(e, sca)apollo_insertScaling(e, sca)
e |
Function, expression, call or symbol to alter. |
sca |
Named numeric vector with the scales. The names in these vectors determine which variables should be scaled. |
A function, expression, call or symbol with the corresponding variables scaled.
Given a numeric object (scalar, vector, matrix or 3-dim array) keeps only the specified rows.
apollo_keepRows(v, r)apollo_keepRows(v, r)
v |
Numeric scalar, vector, matrix or 3-dim array. |
r |
Boolean vector. As many elements as rows in |
The same argument utilities but with the rows where r==FALSE removed.
Given within class probabilities, and class allocation probabilities, calculates the probabilities of an Exploded Logit model and can also perform other operations based on the value of the functionality argument.
apollo_lc(lc_settings, apollo_inputs, functionality)apollo_lc(lc_settings, apollo_inputs, functionality)
lc_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
The returned object depends on the value of argument functionality as follows.
"components": Returns nothing.
"conditionals": Same as "estimate"
"estimate": vector/matrix/array. Returns the probabilities for the chosen alternative for each observation.
"gradient": List containing the likelihood and gradient of the model component.
"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 models components, for each class.
"preprocess": Returns a list with pre-processed inputs, based on lc_settings.
"raw": Same as "prediction"
"report": Class allocation overview.
"shares_LL": Same as "estimate"
"validate": Same as "estimate", but also runs a set of tests on the given arguments.
"zero_LL": Same as "estimate"
Calculates posterior expected values (conditionals) of class allocation probabilities for each individual.
apollo_lcConditionals(model, apollo_probabilities, apollo_inputs)apollo_lcConditionals(model, apollo_probabilities, apollo_inputs)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
This function can only be used with latent class models without continuous heterogeneity.
A matrix with the posterior class allocation probabilities for each individual.
Uses the EM algorithm for estimating a latent class model.
apollo_lcEM( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, lcEM_settings = NA, estimate_settings = NA )apollo_lcEM( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, lcEM_settings = NA, estimate_settings = NA )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
lcEM_settings |
List. Options controlling the EM process.
|
estimate_settings |
List. Options controlling the estimation process within each EM iteration. See apollo_estimate for details. |
This function uses the EM algorithm for estimating a Latent Class model. It is only suitable for models without
continuous mixing. All parameters need to vary across classes and need to be included in the apollo_lcPars
function which is used by apollo_lcEM.
model object
Returns values for random parameters and class allocation probabilities in a latent class model model.
apollo_lcUnconditionals(model, apollo_probabilities, apollo_inputs)apollo_lcUnconditionals(model, apollo_probabilities, apollo_inputs)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
List of object, one per random component and one for the class allocation probabilities.
Calculates the log-likelihood of each model component as well as the whole model.
apollo_llCalc(apollo_beta, apollo_probabilities, apollo_inputs, silent = FALSE)apollo_llCalc(apollo_beta, apollo_probabilities, apollo_inputs, silent = FALSE)
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
silent |
Boolean. If TRUE, no information is printed to the console by the function. Default is FALSE. |
This function calls apollo_probabilities with functionality="output". It then reorders the list of likelihoods so that "model" goes first.
A list of vectors. Each vector corresponds to the log-likelihood of the whole model (first element) or a model component.
Loads a previously estimated model object from a file.
apollo_loadModel(modelName)apollo_loadModel(modelName)
modelName |
Character. Name of the model to load. |
This function looks for a file named modelName_model.rds in the working or output directory, loads the object contained in it, and returns it.
A model object.
Converts choice data from long to wide format, with one row per observation as opposed to one row per alternative/observation.
apollo_longToWide(longData, longToWide_settings)apollo_longToWide(longData, longToWide_settings)
longData |
data.frame. Data in long format. |
longToWide_settings |
List. Contains settings for this function. User input is required for all settings.
|
Silently returns a data.frame with the wide format version of the data. An overview of the data is printed to screen.
Calculates the likelihood ratio test value between two models and reports the corresponding p-value.
apollo_lrTest(model1, model2)apollo_lrTest(model1, model2)
model1 |
Either a character variable with the name of a previously estimated model, or an estimated model in memory, as returned by apollo_estimate. |
model2 |
Either a character variable with the name of a previously estimated model, or an estimated model in memory, as returned by apollo_estimate. |
The two models need to have been estimated on the same data, and one model needs to be nested within the other model.
LR-test p-value (invisibly)
Splits data, creates cluster and loads different pieces of the database on each worker.
apollo_makeCluster( apollo_probabilities, apollo_inputs, silent = FALSE, cleanMemory = FALSE )apollo_makeCluster( apollo_probabilities, apollo_inputs, silent = FALSE, cleanMemory = FALSE )
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
silent |
Boolean. If TRUE, no messages are printed to the terminal. FALSE by default. It overrides |
cleanMemory |
Boolean. If TRUE, it saves apollo_inputs to disc, and removes database and draws from the apollo_inputs in .GlobalEnv and the parent environment. |
Internal use only. Called by apollo_estimate before estimation. Using multiple cores greatly increases memory consumption.
Cluster (i.e. an object of class cluster from package parallel)
Creates a list containing all draws necessary to estimate a model with mixing.
apollo_makeDraws(apollo_inputs, silent = FALSE)apollo_makeDraws(apollo_inputs, silent = FALSE)
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
silent |
Boolean. If true, then no information is printed to console or default output. FALSE by default. |
Internal use only. Called by apollo_validateInputs.
This function creates a list whose elements are the sets of draws requested by the user for use in a model with mixing.
If the model does not include mixing, then it is not necessary to run this function.
The number of draws has a massive impact on memory usage and estimation time. Memory usage and number of computations
scale geometrically as N*interNDraws*intraNDraws (where N is the number of observations). Special care should be taken
when using both inter and intra-individual draws, as memory usage can easily reach the GB order of magnitude. Also, keep in
mind that using several threads (i.e. multicore) at least doubles the memory usage.
This function returns a list, with each element representing a random component of the mixing model. The dimensions
of the array depend on the type of draws used.
If only inter-individual draws are used, then draws are stored as 2-dimensional arrays (i.e. matrices).
If intra-individual draws are used, then draws are stored as 3-dimensional arrays.
The first dimension of the arrays (rows) correspond with the observations in the database.
The second dimension of the arrays (columns) correspond to the number of inter-individual draws.
The third dimension of the arrays correspond to the number of intra-individual draws.
List. Each element is an array of draws representing a random component of the mixing model.
Creates gradient function from the likelihood function apollo_probabilities provided by the user. Returns NULL if the creation of gradient function fails.
apollo_makeGrad( apollo_beta, apollo_fixed, apollo_logLike, validateGrad = FALSE )apollo_makeGrad( apollo_beta, apollo_fixed, apollo_logLike, validateGrad = FALSE )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_logLike |
Function to calculate the log-likelihood of the model, as created by apollo_makeLogLike If provided, the value of the analytical gradient will be compared to the value of the numerical gradient as calculated using apollo_logLike and the numDeriv package. If the difference between the two is bigger than 1 that the analytical gradient is wrong and NULL will be returned. |
validateGrad |
Logical. If TRUE, it compares the value of the analytical gradient evaluated at apollo_beta against the numeric gradient (using numDeriv) at the same value. If the difference is bigger than 1 return NULL. |
Internal use only. Called by apollo_estimate before estimation.
The returned function can be single-threaded or multi-threaded based on the model options.
apollo_gradient function. It receives the following arguments
b Numeric vector of _variable_ parameters (i.e. must not include fixed parameters).
countIter Not used. Included only to mirror inputs of apollo_logLike.
getNIter Not used. Included only to mirror inputs of apollo_logLike.
sumLL Not used. Included only to mirror inputs of apollo_logLike.
writeIter Not used. Included only to mirror inputs of apollo_logLike.
If the creation of the gradient function fails, then it returns NULL.
Creates hessian function from the likelihood function apollo_probabilities provided by the user. Returns NULL if the creation of gradient function fails.
apollo_makeHessian(apollo_beta, apollo_fixed, apollo_logLike)apollo_makeHessian(apollo_beta, apollo_fixed, apollo_logLike)
apollo_beta |
Named numeric vector. Names and values for (all) parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_logLike |
Function to calculate the log-likelihood of the model, as created by apollo_makeLogLike If provided, the value of the analytical gradient will be compared to the value of the numerical gradient as calculated using apollo_logLike and the numDeriv package. If the difference between the two is bigger than 1 that the analytical gradient is wrong and NULL will be returned. |
Internal use only. Called by apollo_estimate before estimation.
The returned function can be single-threaded or multi-threaded based on the model options.
apollo_hessian function. It receives a single argument called b, which are the _variable_
parameters (i.e. must not include fixed parameters).
Creates log-likelihood function from the likelihood function apollo_probabilities provided by the user.
apollo_makeLogLike( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, apollo_estSet = list(estimationRoutine = "bgw"), cleanMemory = FALSE )apollo_makeLogLike( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, apollo_estSet = list(estimationRoutine = "bgw"), cleanMemory = FALSE )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
apollo_estSet |
List of estimation options. It must contain at least one element called estimationRoutine defining the estimation algorithm. See apollo_estimate. |
cleanMemory |
Logical. If TRUE, then |
Internal use only. Called by apollo_estimate before estimation.
The returned function can be single-threaded or multi-threaded based on the model options.
apollo_logLike function.
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.
apollo_mdcev(mdcev_settings, functionality)apollo_mdcev(mdcev_settings, functionality)
mdcev_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
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.
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.
apollo_mdcev2(mdcev_settings, functionality)apollo_mdcev2(mdcev_settings, functionality)
mdcev_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
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.
Calculates the likelihoods of a Multiple Discrete Continuous Nested Extreme Value (MDCNEV) model with an outside good and can also perform other operations based on the value of the functionality argument.
apollo_mdcnev(mdcnev_settings, functionality)apollo_mdcnev(mdcnev_settings, functionality)
mdcnev_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
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 mdcnev_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.
Calculates posterior expected values (conditionals) of continuously distributed random coefficients, as well as their standard deviations.
apollo_mixConditionals(model, apollo_probabilities, apollo_inputs)apollo_mixConditionals(model, apollo_probabilities, apollo_inputs)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
This functions is only meant for use with continuous distributions
List of matrices. Each matrix has dimensions nIndiv x 3. One matrix per random component. Each row of each matrix contains the indivID of an individual, and the posterior mean and s.d. of this random component for this individual
Uses the EM algorithm for estimating a model with continuous random coefficients.
apollo_mixEM( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, mixEM_settings = NA, estimate_settings = NA )apollo_mixEM( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, mixEM_settings = NA, estimate_settings = NA )
apollo_beta |
Named numeric vector. Names and values for parameters. These need to be provided in the following order. With K random parameters, K means for the underlying Normals, followed by the elements of the lower triangle of the Cholesky matrix, by row. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
mixEM_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
estimate_settings |
List. Options controlling the estimation process within each EM iteration. See apollo_estimate for details. |
This function uses the EM algorithm for estimating a model with continuous random coefficients. It is only suitable for models where all parameters are random, with a full covariance matrix. All random parameters need to be based on underlying Normals with a full covariance matrix, but any transform thereof can be used.
model object
Returns draws (unconditionals) for random parameters in model, including interactions with deterministic covariates.
apollo_mixUnconditionals(model, apollo_probabilities, apollo_inputs)apollo_mixUnconditionals(model, apollo_probabilities, apollo_inputs)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
This functions is only meant for use with continuous distributions
List of object, one per random coefficient. With inter-individual draws only, this will be a matrix, with one row per individual, and one column per draw. With intra-individual draws, this will be a three-dimensional array, with one row per observation, inter-individual draws in the second dimension, and intra-individual draws in the third dimension.
Generate random draws using the Modified Latin Hypercube Sampling algorithm.
apollo_mlhs(N, d, i)apollo_mlhs(N, d, i)
N |
Numeric. The number of draws to generate in each dimension |
d |
Numeric. The number of dimensions to generate draws in |
i |
Numeric. The number of individuals to generate draws for |
Internal use only. Algorithm described in Hess, S., Train, K., and Polak, J. (2006) Transportation Research Part B, 40, 147 - 163.
A (N*i) x d matrix with random draws
Calculates the probabilities of a Multinomial Logit model and can also perform other operations based on the value of the functionality argument.
apollo_mnl(mnl_settings, functionality)apollo_mnl(mnl_settings, functionality)
mnl_settings |
List of inputs of the MNL model. It should contain the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
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": List containing the likelihood and gradient of the model component.
"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 probability of the chosen alternative.
"preprocess": Returns a list with pre-processed inputs, based on mnl_settings.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"raw": Same as "prediction"
"report": Choice overview
"shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.
"validate": Same as "estimate"
"zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.
A simulated dataset containing 8,000 mode choices among four alternatives.
apollo_modeChoiceDataapollo_modeChoiceData
A data.frame with 8,000 rows and 25 variables:
Numeric. Identification number of the individual.
Numeric. 1 if the row corresponds to a revealed preference (RP) observation. 0 otherwise.
Numeric. Consecutive ID of RP observations. 0 if SP observation.
Numeric. 1 if the row corresponds to a stated preference (SP) observation. 0 otherwise.
Numeric. Consecutive ID of SP choice tasks. 0 if RP observation.
Numeric. Access time (in minutes) of mode air.
Numeric. Access time (in minutes) of mode bus.
Numeric. Access time (in minutes) of mode rail.
Numeric. 1 if the mode air (plane) is available. 0 otherwise.
Numeric. 1 if the mode bus is available. 0 otherwise.
Numeric. 1 if the mode car is available. 0 otherwise.
Numeric. 1 if the mode rail (train) is available. 0 otherwise.
Numeric. Purpose of the trip. 1 for business, 0 for other.
Numeric. Choice indicator, 1=car, 2=bus, 3=air, 4=rail.
Numeric. Cost (in GBP) of mode air.
Numeric. Cost (in GBP) of mode bus.
Numeric. Cost (in GBP) of mode car.
Numeric. Cost (in GBP) of mode rail.
Numeric. Sex of individual. 1 for female, 0 for male.
Numeric. Income (in GBP per annum) of the individual.
Numeric. Additional services for the air alternative. 1 for no-frills, 2 for wifi, 3 for food. This is not used in the RP data, where it is set to 0.
Numeric. Additional services for the rail alternative. 1 for no-frills, 2 for wifi, 3 for food. This is not used in the RP data, where it is set to 0.
Numeric. Travel time (in minutes) of mode air.
Numeric. Travel time (in minutes) of mode bus.
Numeric. Travel time (in minutes) of mode car.
Numeric. Travel time (in minutes) of mode rail.
This dataset is to be used for discrete choice modelling. Data comes from 500 individuals, each with two revealed preferences (RP) observation, and 14 stated stated (SC) observations. There are 8,000 choices in total. Data is simulated. Each observation contains attributes for the alternatives, availability of alternatives, and characteristics of the individuals.
http://www.apollochoicemodelling.com/
Prints estimation results to console. Amount of information presented can be adjusted through arguments.
apollo_modelOutput(model, modelOutput_settings = NA)apollo_modelOutput(model, modelOutput_settings = NA)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
modelOutput_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
Prints to screen the output of a model previously estimated by apollo_estimate()
A matrix of coefficients, s.d. and t-tests (invisible)
Checks and enhances user defined functions apollo_probabilities, apollo_randCoeff and apollo_lcPars.
apollo_modifyUserDefFunc( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, validate = TRUE, noModification = FALSE )apollo_modifyUserDefFunc( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, validate = TRUE, noModification = FALSE )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names of parameters inside apollo_beta whose values should be kept constant throughout estimation. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
validate |
Logical. If TRUE, the original and modified
|
noModification |
Logical. If TRUE, loop expansion etc are skipped. |
Internal use only. Called by apollo_estimate before estimation.
Checks include: no re-definition of variables, no (direct) calls to database,
calling of apollo_weighting if weights are defined.
List with four elements: apollo_probabilities, apollo_randCoeff, apollo_lcPars and a dummy called success (TRUE if modification was successful, FALSE if not. FALSE will be only be returnes if the modifications are validated).
Calculates the probabilities of a Nested Logit model and can also perform other operations based on the value of the functionality argument.
apollo_nl(nl_settings, functionality)apollo_nl(nl_settings, functionality)
nl_settings |
List of inputs of the NL model. It should contain the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
In this implementation of the Nested Logit model, each nest must have a lambda parameter associated to it.
For the model to be consistent with utility maximisation, the estimated value of the Lambda parameter of all nests
should be between 0 and 1. Lambda parameters are inversely proportional to the correlation between the error terms of
alternatives in a nest. If lambda=1, then there is no relevant correlation between the unobserved
utility of alternatives in that nest.
The tree must contain an upper nest called "root". The lambda parameter of the root is automatically
set to 1 if not specified in nlNests, but can be changed by the user if desired (though not advised).
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 probability of the chosen alternative.
"preprocess": Returns a list with pre-processed inputs, based on nl_settings.
"raw": Same as "prediction"
"report": List with tree structure and choice overview.
"shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.
Calculates density for a Normal distribution at a specific value with a specified mean and standard deviation and can also perform other operations based on the value of the functionality argument.
apollo_normalDensity(normalDensity_settings, functionality)apollo_normalDensity(normalDensity_settings, functionality)
normalDensity_settings |
List of arguments to the functions. It must contain the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
This function calculates the probability of the linear model outcomeNormal = mu + xNormal + epsilon, where epsilon is a random error distributed Normal(0,sigma).
If using this function in the context of an Integrated Choice and Latent Variable (ICLV) model with continuous
indicators, then outcomeNormal would be the value of the indicator, xNormal would be the value of the latent variable (possibly
multiplied by a parameter to measure its correlation with the indicator, e.g. xNormal=lambda*LV), and mu would be
an additional parameter to be estimated (the mean of the indicator, which should be fixed to zero if the indicator is
centered around its mean beforehand).
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 likelihood for each observation.
"gradient": List containing the likelihood and gradient of the model component.
"output": Same as "estimate" but also writes summary of input data to internal Apollo log.
"prediction": Predicted value at the observation level.
"preprocess": Returns a list with pre-processed inputs, based on normalDensity_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.
Calculates the probabilities of an Ordered Logit model and can also perform other operations based on the value of the functionality argument.
apollo_ol(ol_settings, functionality)apollo_ol(ol_settings, functionality)
ol_settings |
List of settings for the OL model. It should include the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
This function estimates an Ordered Logit model of the type:
y* = V + epsilon
outcomeOrdered = 1 if -Inf < y* < tau[1]
2 if tau[1] < y* < tau[2]
...
maxLvl if tau[length(tau)] < y* < +Inf
Where epsilon is distributed standard logistic, and the values 1, 2, ..., maxLvl can be
replaces by coding[1], coding[2], ..., coding[maxLvl].
The behaviour of the function changes depending on the value of the functionality argument.
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": List containing the likelihood and gradient of the model component.
"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 possible levels, with an extra element for the probability of the chosen alternative.
"preprocess": Returns a list with pre-processed inputs, based on ol_settings.
"raw": Same as "prediction"
"report": Dependent variable overview.
"shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.
"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.
Calculates the probabilities of an Ordered Probit model and can also perform other operations based on the value of the functionality argument.
apollo_op(op_settings, functionality)apollo_op(op_settings, functionality)
op_settings |
List of settings for the OP model. It should include the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
This function estimates an ordered probit model of the type:
Where is distributed standard normal, and the values 1, 2, ..., can be
replaced by coding[1], coding[2], ..., coding[maxLvl].
The behaviour of the function changes depending on the value of the functionality argument.
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": List containing the likelihood and gradient of the model component.
"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 possible levels, with an extra element for the probability of the chosen alternative.
"preprocess": Returns a list with pre-processed inputs, based on op_settings.
"raw": Same as "prediction"
"report": Dependent variable overview.
"shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.
"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.
Randomly generates estimation and validation samples, estimates the model on the first and calculates the likelihood for the second, then repeats.
apollo_outOfSample( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, estimate_settings = list(estimationRoutine = "bgw", maxIterations = 200, writeIter = FALSE, hessianRoutine = "none", printLevel = 3L, silent = TRUE), outOfSample_settings = list(nRep = 10, validationSize = 0.1, samples = NA, rmse = NULL) )apollo_outOfSample( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, estimate_settings = list(estimationRoutine = "bgw", maxIterations = 200, writeIter = FALSE, hessianRoutine = "none", printLevel = 3L, silent = TRUE), outOfSample_settings = list(nRep = 10, validationSize = 0.1, samples = NA, rmse = NULL) )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in
|
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
estimate_settings |
List. Options controlling the estimation process. See apollo_estimate. |
outOfSample_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
A common way to test for overfitting of a model is to measure its fit on a sample not used during estimation that is, measuring its out-of-sample fit. A simple way to do this is splitting the complete available dataset in two parts: an estimation sample, and a validation sample. The model of interest is estimated using only the estimation sample, and then those estimated parameters are used to measure the fit of the model (e.g. the log-likelihood of the model) on the validation sample. Doing this with only one validation sample, however, may lead to biased results, as a particular validation sample need not be representative of the population. One way to minimise this issue is to randomly draw several pairs of estimation and validation samples from the complete dataset, and apply the procedure to each pair.
The splitting of the database into estimation and validation samples is done
at the individual level, not at the observation level. If the sampling wants
to be done at the individual level (not recommended on panel data), then the
optional outOfSample_settings$samples argument should be provided.
This function writes two different files to the working/output directory:
modelName_outOfSample_params.csv: Records the
estimated parameters, final log-likelihood, and number of
observations on each repetition.
modelName_outOfSample_samples.csv: Records the
sample composition of each repetition.
The first two files are updated throughout the run of this function, while the last one is only written once the function finishes.
When run, this function will look for the two files above in the working/output directory. If they are found, the function will attempt to pick up re-sampling from where those files left off. This is useful in cases where the original bootstrapping was interrupted, or when additional re-sampling wants to be performed.
A matrix with the average log-likelihood per observation for both the estimation and validation samples, for each repetition. Two additional files with further details are written to the working/output directory.
Receives functions or expressions for each functionality so that a user-defined model can interface with Apollo.
apollo_ownModel(ownModel_settings, functionality)apollo_ownModel(ownModel_settings, functionality)
ownModel_settings |
List of arguments. Only likelihood is mandatory.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
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": List containing the likelihood and gradient of the model component.
"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 probability of the chosen alternative.
"preprocess": Returns a list with pre-processed inputs, based on mnl_settings.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"raw": Same as "prediction"
"report": Choice overview
"shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.
"validate": Same as "estimate"
"zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.
Multiplies likelihood of observations from the same individual, or adds the log of them.
apollo_panelProd(P, apollo_inputs, functionality)apollo_panelProd(P, apollo_inputs, functionality)
P |
List of vectors, matrices or 3-dim arrays. Likelihood of the model components. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
This function should be called inside apollo_probabilities only if the data has a panel structure. It should be called after apollo_avgIntraDraws if intra-individual draws are used.
Argument P with (for most functionalities) the original contents after multiplying across observations at the individual level. Shape depends on argument functionality.
"components": Returns P without changes.
"conditionals": Returns P without averaging across draws. Drops all components except "model".
"estimate": Returns P containing the likelihood of the model after multiplying observations at the individual level. Drops all components except "model".
"gradient": Returns P containing the gradient of the likelihood after applying the product rule across observations for the same individual.
"output": Returns P containing the likelihood of the model after multiplying observations at the individual level.
"prediction": Returns P containing the probabilities/likelihoods of all alternatives for all model components averaged across inter-individual draws.
"preprocess": Returns P without changes.
"raw": Returns P without changes.
"report": Returns P without changes.
"shares_LL": Returns P containing the likelihood of the model after multiplying observations at the individual level.
"validate": Returns P containing the likelihood of the model averaged across inter-individual draws. Drops all components except "model".
"zero_LL": Returns P containing the likelihood of the model after multiplying observations at the individual level.
Calculates apollo_probabilities with functionality="prediction".
apollo_prediction( model, apollo_probabilities, apollo_inputs, prediction_settings = list(), modelComponent = NA )apollo_prediction( model, apollo_probabilities, apollo_inputs, prediction_settings = list(), modelComponent = NA )
model |
Model object. Estimated model object as returned by function apollo_estimate. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
prediction_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
modelComponent |
Deprecated. Same as |
Structure of predictions are simplified before returning, e.g. list of vectors are turned into a matrix.
A list containing predictions for component modelComponent of the model described in apollo_probabilities.
The particular shape of the prediction will depend on the model component.
Checks that the likelihood function for the mode is in the appropriate format to be returned.
apollo_prepareProb(P, apollo_inputs, functionality)apollo_prepareProb(P, apollo_inputs, functionality)
P |
List of vectors, matrices or 3-dim arrays. Likelihood of the model components. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
This function should be called inside apollo_probabilities, near the end of it, just before return(P).
This function only performs checks on the shape of P, but does not change its values.
Argument P with (for most functionalities) the original contents. Output depends on argument functionality.
"components": Returns P without changes.
"conditionals": Returns only the "model" component of argument P.
"estimate": Returns only the "model" component of argument P.
"gradient": Returns only the "model" component of argument P.
"output": Returns argument P without any changes to its content, but gives names to unnamed elements.
"prediction": Returns argument P without any changes.
"preprocess": Returns argument P without any changes to its content, but gives names to elements corresponding to componentNames.
"raw": Returns argument P without any changes.
"report": Returns P without changes.
"shares_LL": Returns argument P without any changes to its content, but gives names to unnamed elements.
"validate": Returns argument P without any changes.
"zero_LL": Returns argument P without any changes to its content, but gives names to unnamed elements.
Pre-process input for multiple models return
apollo_preprocess(inputs, modelType, functionality, apollo_inputs)apollo_preprocess(inputs, modelType, functionality, apollo_inputs)
inputs |
List of settings |
modelType |
Character. Type of model, e.g. "mnl", "nl", "cnl", etc. |
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
The returned object is a pre-processed version of the model settings. This is independent of functionality, but the function is only called during preprocessing.
Prints message to terminal if apollo_inputs$silent is FALSE
apollo_print(txt, nSignifD = 4, widthLim = 11, pause = 0, type = "t")apollo_print(txt, nSignifD = 4, widthLim = 11, pause = 0, type = "t")
txt |
Character, what to print. |
nSignifD |
Optional numeric integer. Minimum number of significant digits when printing numeric matrices. Default is 4. |
widthLim |
Optional numeric integer. Minimum width (in characters) of each column when printing numeric matrices. Default is 11 |
pause |
Scalar integer. Number of seconds the execution will pause after printing the message. Default is 0. |
type |
Character. "t" for regular text (default), "w" for warning, "i" for information. |
Nothing
Reads in parameters from a previously estimated model and copies the values to the given apollo_beta vector, only for those parameters whose name matches.
apollo_readBeta( apollo_beta, apollo_fixed, inputModelName, overwriteFixed = FALSE )apollo_readBeta( apollo_beta, apollo_fixed, inputModelName, overwriteFixed = FALSE )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
inputModelName |
Character. modelName for model from which results are used as starting values. |
overwriteFixed |
Boolean. TRUE if starting values for fixed parameters should also be updated from input file. |
This function will update the values of the parameters in its argument apollo_beta with the matching values in the file
(inputModelName)_estimates.csv. If there is no match for a given parameter in apollo_beta, its value will not be updated.
Named numeric vector. Names and updated starting values for parameters.
Calculates the probabilities of a Random Regret Minimisation model and can also perform other operations based on the value of the functionality argument.
apollo_rrm(rrm_settings, functionality)apollo_rrm(rrm_settings, functionality)
rrm_settings |
List of inputs of the RRM model. It should contain the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
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": List containing the likelihood and gradient of the model component.
"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 probability of the chosen alternative.
"preprocess": Returns a list with pre-processed inputs, based on rrm_settings.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"raw": Same as "prediction"
"report": Choice overview
"shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.
"validate": Same as "estimate"
"zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.
Writes files in the working/output directory with the estimation results.
apollo_saveOutput(model, saveOutput_settings = NA)apollo_saveOutput(model, saveOutput_settings = NA)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
saveOutput_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
Estimation results are saved different files in the working/output directory:
(modelName)_corr.csv CSV file with the estimated classical correlation matrix. Only when bayesian estimation was not used.
(modelName)_covar.csv CSV file with the estimated classical covariance matrix. Only when bayesian estimation was not used.
(modelName)_estimates.csv CSV file with the estimated parameter values, their standars errors, and t-ratios.
(modelName).F12 F12 file with model results. Compatible with ALOGIT.
(modelName)_output.txt Text file with the output produced by function apollo_modelOutput.
(modelName)_robcorr.csv CSV file with the estimated robust correlation matrix. Only when bayesian estimation was not used.
(modelName)_robcovar.csv CSV file with the estimated robust covariance matrix. Only when bayesian estimation was not used.
nothing
Given a set of starting values and a range for them, searches for points with a better likelihood and steeper gradients.
apollo_searchStart( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, searchStart_settings = NA )apollo_searchStart( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, searchStart_settings = NA )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
searchStart_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
This function implements a simplified version of the algorithm proposed by Bierlaire, M., Themans, M. & Zufferey, N. (2010), A Heuristic for Nonlinear Global Optimization, INFORMS Journal on Computing, 22(1), pp.59-70. The main difference lies in it implementing only two out of three tests on the candidates described by the authors. The implemented algorithm has the following steps.
Randomly draw nCandidates candidates from an interval given by the user.
Label all candidates with a valid log-likelihood (LL) as active.
Apply bfgsIter iterations of the BFGS algorithm to each active candidate.
Apply the following tests to each active candidate:
Has the BGFS search converged?
Are the candidate parameters after BFGS closer than dTest from any other candidate with higher LL?
Is the LL of the candidate after BFGS further than distLL from a candidate with better LL, and its gradient smaller than gTest?
Mark any candidates for which at least one test results in yes as inactive.
Go back to step 3, unless only one candidate is active, or the maximum number of iterations (maxStages) has been reached.
This function will write a CSV file to the working/output directory summarising progress. This file is called modelName_searchStart.csv .
named vector of model parameters. These are the best values found.
Given a numeric object (scalar, vector, matrix or 3-dim array) sets a subset of rows to a given value.
apollo_setRows(v, r, val)apollo_setRows(v, r, val)
v |
Numeric scalar, vector, matrix or 3-dim array. Rows of this object will be replaced by |
r |
Boolean vector. As many elements as rows in |
val |
Numeric scalar. Value to which the specified rows must be set to. |
The same argument utilities but with the rows where r==TRUE set to val.
Starts or stops writing the output shown in the console to a file named "modelName_additional_output.txt".
apollo_sink(apollo_inputs = NULL)apollo_sink(apollo_inputs = NULL)
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. If not provided, it will be looked for in the global environment. |
After the first time this function is called, all output shown in the console will also be written to a text file called "modelName_additional_output.txt", where "modelName" is the modelName set inside apollo_control. The second time this function is called, it stops writing the console output to the file. The user should always call this function an even number of times to close the output file and prevents data loss.
Nothing.
Measures the evaluation time of a model for different number of cores and draws.
apollo_speedTest( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, speedTest_settings = NA )apollo_speedTest( apollo_beta, apollo_fixed, apollo_probabilities, apollo_inputs, speedTest_settings = NA )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
speedTest_settings |
List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.
|
This function evaluates the function apollo_probabilities several times using different number of threads (a.k.a. processor cores),
and draws (if the model uses mixing). It then plots the estimation time for each combination.
Estimation time grows at least linearly with number of draws, while time savings decrease with the number of threads.
This function can help decide what number of draws and cores to use for estimation, though a high number of draws is always
recommended. If the computer will be used for additional activities during estimation, no more than (machine number of cores - 1) should be used.
Using more threads than cores available in the machine will lead to reduce dperformance.
The use of additional cores come at the expense of additional memory usage. If R uses more memory than the physical RAM available,
then significant slow-downs in processing time can be expected. This function can help avoiding such pitfalls.
A matrix with the average time per evaluation for each number of threads and draws combination. A graph is also plotted.
A Stated Preference dataset containing 3,492 route choices among two alternatives.
apollo_swissRouteChoiceDataapollo_swissRouteChoiceData
A data frame with 3,492 rows and 16 variables:
Numeric. Identification number of the individual.
Numeric. Choice indicator, 1 for alternative 1, and 2 for alternative 2.
Numeric. Travel time (in minutes) for alternative 1.
Numeric. Travel cost (in CHF) for alternative 1.
Numeric. Headway time (in minutes) for alternative 1.
Numeric. Number of interchanges for alternative 1.
Numeric. Travel time (in minutes) for alternative 2.
Numeric. Travel cost (in CHF) for alternative 2.
Numeric. Headway time (in minutes) for alternative 2.
Numeric. Number of interchanges for alternative 2.
Numeric. Household income (in CHF per annum).
Numeric. 1 if respondent has a car available, 0 otherwise.
Numeric. 1 if the purpose of the trip is commuting. 0 otherwise.
Numeric. 1 if the purpose of the trip is shopping. 0 otherwise.
Numeric. 1 if the purpose of the trip is business. 0 otherwise.
Numeric. 1 if the purpose of the trip is leisure. 0 otherwise.
This dataset is to be used for discrete choice modelling. Data comes from 388 individuals who participated in a Stated Choice (SC) survey, providing a total of 3,492 observations. Each choice scenario includes two alternatives described in terms of travel time, cost, headway and interchanges. Additional information on respondents is available. This dataset comes from the following publication. Vrtic, M. & Axhausen, K.W. (2003), The impact of tilting trains in Switzerland: A route choice model of regional and long distance public transport trips. 82nd annual meeting of the transportation research board, Washington, DC.
http://www.apollochoicemodelling.com/
A Revealed Preference dataset containing 2,826 full-day observations.
apollo_timeUseDataapollo_timeUseData
An object of class data.frame with 2826 rows and 20 columns.
This dataset is to be used for Multiple Discrete Continuous (MDC) modelling. Data comes from 447 individuals who provided activitry diaries for a total of 2,826 days. Each observation summarizes the amount of time spent in each of twelve different activities. The dataset also incluides characteristics of the participants. This dataset comes from the following publication. Calastri, C., Crastes dit Sourd, R. and Hess, S. (2020) We want it all: experiences from a survey seeking to capture social network structures, lifetime events and short-term travel and activity planning. Transportation, 47(1), pp. 175-201.
Numeric. Identification number of the individual.
Numeric. Index of the day for each observation (day 1 was excluded).
Numeric. Date in format yyyymmdd.
Numeric. Total amount of time registered during the day (in minutes).
Numeric. Time spent dropping-of or picking up other people (in minutes).
Numeric. Time spent working (in minutes).
Numeric. Time spent on educational activities (in minutes).
Numeric. Time spent shopping (in minutes).
Numeric. Time spent on private business (in minutes).
Numeric. Time spent getting petrol (in minutes).
Numeric. Time spent on social or leasure activities (in minutes).
Numeric. Time spent on vacation or long (inter-city) travel (in minutes).
Numeric. Time spent doing exercise (in minutes).
Numeric. Time spent at home (in minutes).
Numeric. Time spent travelling (everyday travelling) (in minutes).
Numeric. Non-allocated time (in minutes).
Numeric. 1 if respondent is female. 0 otherwise.
Numeric. Age of respondent (in years, approximate).
Numeric. 1 if the respondent works full time.
Numeric. 1 if the current date is a weekend.
http://www.apollochoicemodelling.com/
Calculates density for a censored Normal distribution at a specific value with a specified mean and standard deviation and user provided bounds, and can also perform other operations based on the value of the functionality argument.
apollo_tobit(tobit_settings, functionality)apollo_tobit(tobit_settings, functionality)
tobit_settings |
List of arguments to the functions. It must contain the following.
|
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
This function calculates the probability of the linear model outcomeTobit = mu + xTobit + epsilon, where epsilon is a random error distributed Normal(0,sigma), but with optional lower and upper bounds imposed by the user (outside of which the density would be 0).
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 likelihood for each observation.
"gradient": List containing the likelihood and gradient of the model component.
"output": Same as "estimate" but also writes summary of input data to internal Apollo log.
"prediction": Predicted value at the observation level.
"preprocess": Returns a list with pre-processed inputs, based on tobit_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.
Returns unconditionals for random parameters in model, both for continuous mixtures and latent class.
apollo_unconditionals(model, apollo_probabilities, apollo_inputs)apollo_unconditionals(model, apollo_probabilities, apollo_inputs)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
apollo_probabilities |
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
|
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
This functions is only meant for use with models using continuous distributions or latent classes, or both at the same time.
Depends on whether the model uses continuous mixtures or latent class.
If the model contains a continuous mixture, it returns a list with one object per random coefficient. When using inter-individual draws only, each element will be a matrix with one row per individual, and one column per draw. When using intra- individual draws, each element will be a three-dimensional array, with one row per observation, inter-individual draws in the second dimension, and intra- individual draws in the third dimension.
If the model contains latent classes, it returns a list with as many elements as random coefficients in the model, plus one additional element containing the class allocation probabilities.
If the model contains both continuous mixing and latent classes, a list with the two elements described above will be returned.
Pre-process input for common models return
apollo_validate(inputs, modelType, functionality, apollo_inputs)apollo_validate(inputs, modelType, functionality, apollo_inputs)
inputs |
List of settings |
modelType |
Character. Type of model, e.g. "mnl", "nl", "cnl", etc. |
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
apollo_inputs |
List of main inputs to the model estimation process. See apollo_validateInputs. |
The returned object depends on the value of argument operation
Validates the options controlling the running of the code apollo_control and sets default values for the omitted ones.
apollo_validateControl(database, apollo_control, silent = FALSE)apollo_validateControl(database, apollo_control, silent = FALSE)
database |
data.frame. Data used by model. |
apollo_control |
List. Options controlling the running of the code. User input is required for all settings except those with a default or marked as optional.
|
silent |
Boolean. If TRUE, no messages are printed to screen. |
This function should be run before running apollo_validateData.
Validated version of apollo_control, with additional element called panelData set to TRUE for repeated choice data.
Checks consistency of the database with apollo_control, sorts it by
indivID, and adds an internal ID variable (apollo_sequence)
apollo_validateData(database, apollo_control, silent)apollo_validateData(database, apollo_control, silent)
database |
data.frame. Data used by model. |
apollo_control |
List. Options controlling the running of the code. See apollo_validateInputs. |
silent |
Boolean. TRUE to prevent the function from printing to the console. Default is FALSE. |
This function should be called after calling apollo_validateControl.
Observations are sorted only if apollo_control$panelData=TRUE.
Data.frame. Validated version of database.
apollo_HB list of parametersValidates the apollo_HB list of parameters and sets default values for the omitted ones.
apollo_validateHBControl( apollo_HB, apollo_beta, apollo_fixed, apollo_control, silent = FALSE )apollo_validateHBControl( apollo_HB, apollo_beta, apollo_fixed, apollo_control, silent = FALSE )
apollo_HB |
List. Contains options for Bayesian estimation. See
|
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
apollo_control |
List. Options controlling the running of the code. See apollo_validateInputs. |
silent |
Boolean. TRUE to keep the function from printing to the console. Default is FALSE. |
This function is only necessary when using bayesian estimation.
Validated apollo_HB
apollo_estimate
Searches the user work space (.GlobalEnv) for all necessary input to run apollo_estimate, and packs it in a single list.
apollo_validateInputs( apollo_beta = NA, apollo_fixed = NA, database = NA, apollo_control = NA, apollo_HB = NA, apollo_draws = NA, apollo_randCoeff = NA, apollo_lcPars = NA, recycle = FALSE, silent = FALSE )apollo_validateInputs( apollo_beta = NA, apollo_fixed = NA, database = NA, apollo_control = NA, apollo_HB = NA, apollo_draws = NA, apollo_randCoeff = NA, apollo_lcPars = NA, recycle = FALSE, silent = FALSE )
apollo_beta |
Named numeric vector. Names and values for parameters. |
apollo_fixed |
Character vector. Names (as defined in |
database |
data.frame. Data used by model. |
apollo_control |
List. Options controlling the running of the code. User input is required for all settings except those with a default or marked as optional.
|
apollo_HB |
List. Contains options for Bayesian estimation. See
|
apollo_draws |
List of arguments describing the inter and intra individual draws. Required only if
|
apollo_randCoeff |
Function. Used with mixing models. Constructs the random parameters of a mixing model. Receives two arguments:
|
apollo_lcPars |
Function. Used with latent class models. Constructs a list of parameters for each latent class. Receives two arguments:
|
recycle |
Logical. If TRUE, an older version of |
silent |
Logical. TRUE to keep the function from printing to the console. Default is FALSE. |
All arguments to this function are optional. If the function is called without arguments, then it it will look in the user workspace (i.e. the global environment) for variables with the same name as its omitted arguments. We strongly recommend users to visit http://www.apollochoicemodelling.com/ for examples on how to use Apollo. In the website, users will also find a detailed manual and a user-group for help and further reference.
List grouping several required input for model estimation.
Calculates the Hessian, variance-covariance matrix and standard errors of an Apollo model as defined by its likelihood function
and apollo_inputs list of settings. Performs automatic scaling for increased numeric stability.
apollo_varcov(apollo_beta, apollo_fixed, varcov_settings)apollo_varcov(apollo_beta, apollo_fixed, varcov_settings)
apollo_beta |
Named numeric vector. Names and values of parameters at which to calculate the covariance matrix. Values must not be scaled, and they must include any fixed parameter. |
apollo_fixed |
Character vector. Names of fixed parameters. |
varcov_settings |
List of settings defining the behaviour of this function. It must contain at least one of
the following:
|
It calculates the Hessian, variance-covariance, and standard errors at apollo_beta values of an
estimated model. At least one of the following settings must be provided (ordered by speed of computation): apollo_grad,
apollo_logLike, or (apollo_probabilities and apollo_inputs). If more than one is provided,
then the priority is: apollo_grad, apollo_logLike, (apollo_probabilities and apollo_inputs).
List with the following elements
apollo_beta: Named numerical vector. Parameter estimates (model$estimate, not scaled).
corrmat: Numerical matrix. Correlation between parameter estimates.
hessian: Numerical matrix. Hessian of the model at parameter estimates (model$estimate).
hessianScaling: Named numeric vector. Scales used on the paramaters to calculate the Hessian (non-fixed only).
methodsAttempted: Character vector. Name of methods attempted to calculate the Hessian.
methodUsed: Character. Name of method used to calculate the Hessian.
robcorrmat: Numerical matrix. Robust correlation between parameter estimates.
robse: Named numerical vector. Robust standard errors of parameter estimates.
robvarcov: Numerical matrix. Robust variance-covariance matrix.
se: Named numerical vector. Standard errors of parameter estimates.
varcov: Numerical matrix. Variance-covariance matrix.
Returns a list containing the names and definitions of variables in f, apollo_randCoeff and apollo_lcPars
apollo_varList(f, apollo_inputs)apollo_varList(f, apollo_inputs)
f |
A function, usually |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
It looks for variable definitions inside f, apollo_randCoeff, and apollo_lcPars. It returns
them in a list.
A list of expressions containing all definitions in f, apollo_randCoeff and apollo_probabilities
Applies weights to individual observations in likelihood function.
apollo_weighting(P, apollo_inputs, functionality)apollo_weighting(P, apollo_inputs, functionality)
P |
List of vectors, matrices or 3-dim arrays. Likelihood of the model components. |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
functionality |
Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call
|
The likelihood (i.e. probability in the case of choice models) of the model in the appropriate form for the given functionality, multiplied by individual-specific weights.
Writes an F12 file (ALogit format) with the results of a model estimation.
apollo_writeF12(model, truncateCoeffNames = TRUE)apollo_writeF12(model, truncateCoeffNames = TRUE)
model |
Model object. Estimated model object as returned by function apollo_estimate. |
truncateCoeffNames |
Boolean. TRUE to truncate parameter names to 10 characters. TRUE by default. |
Nothing.
modelname_iterations.csv
Writes the vector [beta,ll] to a file called modelname_iterations.csv
apollo_writeTheta( beta, ll, modelName, scaling = NULL, outDir = NULL, apollo_beta = NULL )apollo_writeTheta( beta, ll, modelName, scaling = NULL, outDir = NULL, apollo_beta = NULL )
beta |
vector of parameters to be written (including fixed ones). |
ll |
scalar representing the log-likelihood of the whole model. |
modelName |
Character. Name of the model. |
scaling |
Numeric vector of scales applied to beta |
outDir |
Scalar character. Name of output directory |
apollo_beta |
Named numeric vector of starting values. |
Nothing.
Validates and expands rows if necessary.
aux_validateRows(rows, componentName = NULL, apollo_inputs = NULL)aux_validateRows(rows, componentName = NULL, apollo_inputs = NULL)
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 |
componentName |
Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in |
apollo_inputs |
List grouping most common inputs. Created by function apollo_validateInputs. |
Receives an estimated model object and prints a brief summary using the generic print function.
## S3 method for class 'apollo' print(x, ...)## S3 method for class 'apollo' print(x, ...)
x |
Model object. Estimated model object as returned by function apollo_estimate. |
... |
further arguments passed to or from other methods. |
nothing.
Receives an estimated model object and prints a summary using the generic summary function.
## S3 method for class 'apollo' summary(object, ..., pTwoSided = FALSE)## S3 method for class 'apollo' summary(object, ..., pTwoSided = FALSE)
object |
Model object. Estimated model object as returned by function apollo_estimate. |
... |
further arguments passed to or from other methods. |
pTwoSided |
Logical. Should two-sided p-values be printed instead of one-sided p-values. FALSE by default. #' @return nothing. |