CODE
The software on this site comes with no guarantees and the authors cannot be held liable for any errors. Users of Apollo are asked to acknowledge the use of the software by citing the academic paper and noting the version of Apollo used in their work.
» Hess, S. & Palma, D. (2019), Apollo: a flexible, powerful and customisable freeware package for choice model estimation and application, Journal of Choice Modelling, Volume 32, September 2019, 100170
The latest full release of Apollo is always hosted on CRAN and we recommend installing it via install.packages("apollo"). When using the CRAN release, we recommend installation using binaries rather than building from source.
For an overview of changes across versions, see below.
Users can also download legacy and development versions. The versions available on this website need to be compiled from source.
Version | Status | Release date | Source code |
---|---|---|---|
v0.3.4 | released | 1 October 2024 | apollo_0.3.4.tar.gz |
v0.3.3 | released | 4 June 2024 | apollo_0.3.3.tar.gz |
v0.3.2 | released | 15 April 2024 | apollo_0.3.2.tar.gz |
v0.3.1 | released | 12 October 2023 | apollo_0.3.1.tar.gz |
v0.3.0 | released | 10 August 2023 | apollo_0.3.0.tar.gz |
v0.2.9 | released | 13 May 2023 | apollo_0.2.9.tar.gz |
v0.2.8 | released | 8 September 2022 | apollo_0.2.8.tar.gz |
v0.2.7 | released | 26 January 2022 | apollo_0.2.7.tar.gz |
v0.2.6 | released | 8 November 2021 | apollo_0.2.6.tar.gz |
v0.2.5 | released | 31 July 2021 | apollo_0.2.5.tar.gz |
v0.2.4 | released | 25 February 2021 | apollo_0.2.4.tar.gz |
v0.2.3 | released | 20 January 2021 | apollo_0.2.3.tar.gz |
v0.2.2 | released | 5 December 2020 | apollo_0.2.2.tar.gz |
v0.2.1 | released | 28 October 2020 | apollo_0.2.1.tar.gz |
v0.2.0 | released | 19 October 2020 | apollo_0.2.0.tar.gz |
v0.1.1 | unreleased version | (last update 15 September 2020) | apollo_0.1.1.tar.gz |
v0.1.0 | released | 16 March 2020 | apollo_0.1.0.tar.gz |
v0.0.9 | released | 23 October 2019 | apollo_0.0.9.tar.gz |
v0.0.8 | released | 9 September 2019 | apollo_0.0.8.tar.gz |
v0.0.7 | released | 8 May 2019 | apollo_0.0.7.tar.gz |
v0.0.6 | released | 13 March 2019 | apollo_0.0.6.tar.gz |
HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.2.9 (13 May 2023)
Changes to Apollo code:
General
Minor improvements to efficiency, stability and reporting of user errors.
Dropping pre-estimation diagnostics with RSGHB
Functions affected: apollo_estimate with apollo_control$HB=TRUE
Detailed description: The RSGHB setting nodiagnostics is set to TRUE by default
Backwards compatibility of code: no backwards compatibility issues for existing functions
Mixture models no longer require apollo_control$mixing=TRUE
Functions affected: apollo_validateInputs
Detailed description: The setting apollo_control$mixing is now set to TRUE automatically when apollo_draws is present
Backwards compatibility of code: no backwards compatibility issues for existing functions
More detailed reporting of properties of Hessian matrix
Functions affected: apollo_modelOutput and apollo_saveOutput
Detailed description: Additional properties about the maximum likelihood estimate are reported
Backwards compatibility of code: no backwards compatibility issues for existing functions
New function for reshaping long data
Functions affected: apollo_longToWide
Detailed description: A new function was added to translate data from long format to wide format
Backwards compatibility of code: no backwards compatibility issues for existing functions
BHHH standard errors saved and printed
Functions affected: apollo_estimate, apollo_saveOutput
Detailed description: BHHH standard errors are now saved in the model object and are also printed to screen at the end of estimation, prior to the calculation of the asymptotic variance-covariance matrix
Backwards compatibility of code: no backwards compatibility issues for existing functions
New capability to calculate standard errors for all ratios and differences for all pairs of parameters
Functions affected: apollo_deltaMethod
Detailed description: A new setting can be used with apollo_deltaMethod to compute standard errors for ratios and differences of all pairs of parameters at the same time
Backwards compatibility of code: no backwards compatibility issues for existing functions
RMSE calculation added to apollo_outOfSample
Functions affected: apollo_outOfSample
Detailed description: RMSE calculations are now reported when calling apollo_outOfSample
Backwards compatibility of code: no backwards compatibility issues for existing functions
New function for Random Regret Minimisation
Functions affected: apollo_rrm
Detailed description: New function no longer requiring manual coding of RRM
Backwards compatibility of code: no backwards compatibility issues for existing functions
New function for Extended Multiple Discrete Continuous model
Functions affected: apollo_emdc
Detailed description: New function for the extended multiple discrete continuous model of ?
Backwards compatibility of code: no backwards compatibility issues for existing functions
Extensive changes to outputs from HB estimation
Functions affected: apollo_modelOutput and apollo_saveOutput with apollo_control$HB==TRUE
Detailed description: Extensive changes have been made, as follows:
- RSGHB log file no longer printed but equivalent outputs included in Apollo output file
- RSGHB component renamed:
- A now called HB_iterations_means
- B now called HB_indiv_draws_means
- Bsd now called HB_indiv_draws_sd
- C now called HB_ posterior_means
- Csd now called HB_ posterior_sd
- D now called HB_iterations_covar
- F now called HB_iterations_non_random
- HB outputs at iteration level no longer automatically included in saved model object. Optionally included in model object by setting saveOutput_settings$saveHBiterations=TRUE (default=FALSE)
- Geweke test outputs saved under new names in model object, printing now controlled by new setting saveOutput_settings$printHBconvergence
- Individual-level draws still included by default in model object, but no longer automatically written to a separate file
- Individual level posteriors still included by default in model object, and automatically written to file, except if saveOutput_settings$saveEst==FALSE
- Summary for underlying Normals still saved in model object, but no longer written to separate file
Backwards compatibility of code: outputs changed, including names, potentially affecting old use of results
Detailed description: New version of RRM example, now using apollo_rrm
Backwards compatibility of examples: New version only works from version 0.2.9 onwards
Examples affected: eMDC_with_budget.r and eMDC_without_budget.r
Detailed description: New version of EMDC examples, now using apollo_emdc
Backwards compatibility of examples: New versions only work from version 0.2.9 onwards
Fixed a bug where no model object was produced if estimation failed when rescaling model parameters
apollo_estimate with apollo_control$HB=TRUE
Fixed bug that led to a failure when using a single random term with Bayesian estimation
apollo_estimate with estimate_settings$scaling
Fixed bug where scaling in estimation provided by the user was not used
apollo_estimate with weights
Weighting was not taken into account in reporting of LLstart
Preprocessing and model validation
Fixed a bug where failures during model validation led to an error message about duplicate component names
Calculation of adjusted rho2 against observed shares model
The number of parameters is now adjusted by the number of constants that would be estimated in an observed shares model
Version 0.2.8 (8 September 2022)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
Single function for conditionals
Functions affected: apollo_conditionals
Detailed description: The user can now use the function apollo_conditionals for continuous mixture models or latent class, no longer needing apollo_lcConditionals
Backwards compatibility of code: old syntax still works too
Single function for unconditionals
Functions affected: apollo_unconditionals
Detailed description: The user can now use the function apollo_unconditionals for continuous mixture models or latent class, no longer needing apollo_lcUnconditionals
Backwards compatibility of code: old syntax still works too
Changes to saved model object when using Bayesian estimation
Functions affected: apollo_saveOutput with apollo_control$HB=TRUE
Detailed description: Apollo no longer includes cmcLLout and cmcRLHout in the saved model object - these were rarely if ever used and took up substantial space. If a user requires them, they are available in the model object in memory after estimation, and can be saved to file.
Backwards compatibility of code: no backwards compatibility issues
Model inputs now also saved with HB
Functions affected: apollo_modelOutput and apollo_saveOutput with apollo_control$HB=TRUE
Detailed description: The setting printFunctions now also works with Bayesian estimation.
Backwards compatibility of code: No backwards compatibility issues as old input still accepted and new inputs are optional.
Model object saved before covariance matrix calculation
Functions affected: apollo_estimate
Detailed description: If a model takes longer than 10 minutes to estimate, the model object is written to disk prior to the covariance matrix calculation.
Backwards compatibility of code: No backwards compatibility issues.
Ability to report p-values in Delta method calculations
Functions affected: apollo_deltaMethod
Detailed description: A new setting printPVal is now available for apollo_deltaMethod.
Backwards compatibility of code: No backwards compatibility issues as this is an optional setting.
Detailed description: apollo_conditionals now used instead of apollo_lcConditionals
Backwards compatibility of examples: old versions of example still function too
Examples affected: LC_with_covariates.r
Detailed description: apollo_unconditionals now used instead of apollo_lcUnconditionals
Backwards compatibility of examples: old versions of example still function too
Examples affected: BW_simultaneous.r
Detailed description: An earlier version of this example file had unused code that was still computing the probabilities for best choice only
Backwards compatibility of examples: old versions of example still function too
Examples affected: MMNL_preference_space.r and Hybrid_with_OL.r
Detailed description: An illustration of the use of apollo_choiceAnalysis on unlabelled data is now included
Backwards compatibility of examples: old versions of example still function too
Fixed a bug that led to an error in the reporting of class allocation probabilities
apollo_ol and apollo_op
Fixed a bug that led to a failure in ordered logit and ordered probit if the levels in rows that were filtered out were different from those used in other rows
apollo_estimate
Fixed a bug in reporting failures at the initial LL with multi-component models
apollo_estimate
Fixed issue with iterations file having additional columns after first iteration, only happened with analytical gradients and fixed params
apollo_panelProd
Fixed an unhelpful error message if apollo_panelProd was called when not needed
apollo_saveOutput with writeF12==TRUE
Fixed a bug that made writing F12 files incompatible with R 4.2.0 onwards
apollo_basTest
Fixed a bug where the Ben-Akiva & Swait test could not find the rho2 statistics from saved models
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.2.7 (26 January 2022)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
Fractional logit model added to Apollo
Functions affected: apollo_fmnl
Detailed description: The user can now use the Fractional Multinominal Logit (FMNL) model
Backwards compatibility of code: new capability, no backwards compatibility issues
apollo_deltaMethod now allows for user-defined functions
Functions affected: apollo_deltaMethod
Detailed description: The user can now create any function of parameters and evaluate its standard error using the Delta method, and do so for multiple functions at the same time
Backwards compatibility of code: old syntax still works too
Syntax now uses classes instead of alternatives in class allocation model
Functions affected: apollo_classAlloc
Detailed description: The user can now use classes inside the settings for apollo_classAlloc instead of alternatives
Backwards compatibility of code: old syntax still works too
Detailed description: apollo_deltaMethod now uses expression
Backwards compatibility of examples: old versions of examples still function too
Examples affected: FMNL.r
Detailed description: New example added using apollo_fmnl on apollo_timeUseData
Backwards compatibility of examples: new example requires version 0.2.7 onwards
Examples affected: RRM.r
Detailed description: This example was previously missing the availabilities in calculating the regret functions
Backwards compatibility of examples: previous versions were incorrect
Ability to use utilities instead of V was missing
apollo_choiceAnalysis
Fixed a bug that caused an error when an alternative was never chosen
apollo_prediction
Fixed bug that led to wrong market share when rows was used
apollo_lrTest
Fixed bug that led to a failure of the likelihood ratio test function for models with multiple components (i.e. using apollo_combineModels)
apollo_ol and apollo_op with rows
Fixed bug that led to a failure when thresholds were not scalars and when the rows setting was used
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.2.6 (8 November 2021)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
Non-BFGS algorithms cannow also produce file with iterations
Functions affected: apollo_estimate
Detailed description: Non-BFGS algorithms can now also write iterations to file.
Backwards compatibility of code: new capability, no backwards compatibility issues
User can disable calculation of log-likelihood at constants
Functions affected: apollo_control settings
Detailed description: The user can now specify whether the log-likelihood at constants should be calculated, using the setting calculateLLC in apollo_control. This is set to TRUE by default
Backwards compatibility of code: new capability, no backwards compatibility issues
New function for latent class allocation model
Functions affected: apollo_classAlloc
Detailed description: A new function apollo_classAlloc has been included to compute class allocation probabilities for MNL
Backwards compatibility of code: updates to syntax, but old approach still works too
Syntax uses utilities instead of V
Functions affected: all model functions using utilities
Detailed description: The user can now use utilities inside the model settings instead of V
Backwards compatibility of code: old syntax still works too
ρ2 at constants also reported
Functions affected: apollo_modelOutput and apollo_saveOutput
Detailed description: ρ2 measures are now reported against a model with constants only, in addition to against a model with equal shares
Backwards compatibility of code: new output, no backwards compatibility issues
Average prediction added to output of apollo_prediction for discrete choice models
Functions affected: apollo_prediction
Detailed description: the use of apollo_prediction with discrete choice models now leads to the reporting of average predictions in addition to aggregate predictions
Backwards compatibility of code: new output, no backwards compatibility issues
Detailed description: New names and contents for all examples
Backwards compatibility of examples: no longer compatible with earlier versions of the manual
apollo_estimateHB with apollo_control$noValidation=TRUE
Fixed a bug that caused a failure of estimation
apollo_estimate with constraints
Fixed a bug that led to a failure with equality constraints
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.2.5 (31 July 2021)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
User can specify number of replications to use in predictions from MDCEV
Functions affected: apollo_prediction with apollo_mdcev and apollo_mdcnev
Detailed description: The Pinjari & Bhat forecasting algorithm uses replications, and the user can now provide this as an additional settings named rep in prediction_settings.
Backwards compatibility of code: new capability, no backwards compatibility issues
More detailed outputs for MDCEV predictions
Functions affected: apollo_prediction with apollo_mdcev and apollo_mdcnev
Detailed description: The prediction from MDCEV models now returns the mean and standard deviations of continuous demand (cont_mean, cont_sd), discrete demand (disc_mean, disc_sd), and expenditure (expe_mean, exp_sd).
Backwards compatibility of code: new output format, no backwards compatibility issues
Predictions with multiple component components
Functions affected: apollo_prediction with apollo_combineModels
Detailed description: apollo_prediction with multiple model components now returns a list of data.frame, one for each model component. Model components without prediction capabilities are omitted from the return. If runs>1, then a data.frame with the point estimates are given AND a 3-dim array with the repetitions as well (the array does not have the IDs)
Backwards compatibility of code: new output format, some ancillary code may need to be updated
Output directory can be set by the user
Functions affected: all functions reading and writing to files
Detailed description: the user can specify an optional argument outputDirectory in apollo_control which will be used for outputs.
Backwards compatibility of code: new capability, no backwards compatibility issues
Output returned by apollo_sharesTest
Functions affected: apollo_sharesTest
Detailed description: In addition to screen output, apollo_sharesTest also invisibly returns the output so it can be saved into a data.frame
Backwards compatibility of code: new capability, no backwards compatibility issues
Detailed description: All examples changed to use output directory
Backwards compatibility of examples: affected part only works from version 0.2.5 onwards
Examples affected: apollo_example_26.r
Detailed description: Added calls to apollo_validateInputs after making changes to data
Backwards compatibility of examples: change required from version 0.2.5 onwards
Examples affected: apollo_example_27/r
Detailed description: removed parameters common across classes
Backwards compatibility of examples: EM algorithm implementation does not allow for shared parameters from version 0.2.5 onwards
Fixed a bug that led to failures when users provided their own coding of levels
apollo_cnl
Fixed a bug that failed to correctly diagnose when allocation parameters did not sum to 1 at the starting values
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.2.4 (25 February 2021)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
Monte Carlo replications for MDCEV can now be set by user
Functions affected: apollo_prediction with apollo_mdcev, apollo_mdcnev
Detailed description: the user can now set the number of Monte Carlo replications to use when predicting from MDCEV models
Backwards compatibility of code: new optional argument, no backwards compatibility issues
MDCEV predictions now include expenditure
Functions affected: apollo_prediction with apollo_mdcev, apollo_mdcnev
Detailed description: the output from apollo_prediction for MDCEV models now includes the expenditure
Backwards compatibility of code: new output, no backwards compatibility issues
Predictions now returned as data.frame instead of matrix
Functions affected: apollo_prediction
Detailed description: the output from apollo_prediction is now a data.frame instead of a matrix, which helps avoid issues with non-numeric IDs
Backwards compatibility of code: new output format, some possible backwards compatibility issues with examples
apollo_sharesTest now returns output
Functions affected: apollo_sharesTest
Detailed description: the output from apollo_prediction is now not just printed to screen, but also returned
Backwards compatibility of code: new output format, no backwards compatibility issues
apollo_dft
Fixed a bug where apollo_dft could fail in mixture models
apollo_prediction with apollo_mdcev, apollo_mdcnev
Fixed a bug where apollo_predictions could produce errors when asking for confidence intervals with MDCEV models
apollo_cnl
Fixed a bug where apollo_cnl would not check for allocation parameters to sum to 1
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.2.3 (20 January 2021)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
None apollo_estimate
Fixed a bug where apollo_estimate could fail due to missing arguments, where this is now checked before estimation starts
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.2.2 (5 December 2020)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
New options for shares test added added
Functions affected: apollo_sharesTest
Detailed description: the user can now create pseudo-alternatives, grouping together existing alternatives
Backwards compatibility of code: new optional argument, no backwards compatibility issues
User can omit avail when all alternatives are available
Functions affected: apollo_mnl, apollo_nl, apollo_cnl, apollo_dft, apollo_el, apollo_mdcev, apollo_mdcnev
Detailed description: the user can now omit the avail argument if all alternatives are available
Backwards compatibility of code: optional, no backwards compatibility issues
Improved counting of modelled outcomes
Functions affected: apollo_modelOutput and apollo_saveOutput
Detailed description: the output now counts modelled outcomes as opposed to rows in the data, which leads to different statistics for multi-component models
Backwards compatibility of code: outputs changed, with resulting changes in goodness-of-fit statistics
Optionally drop fixed parameters from output
Functions affected: apollo_modelOutput and apollo_saveOutput
Detailed description: the user can now optionally exclude fixed parameters from the output
Backwards compatibility of code: outputs changed
Optionally return only the model component when using apollo_combineModels
Functions affected: apollo_combineModels
Detailed description: the user can now optionally exclude subcomponents when calling apollo_combineModels
Backwards compatibility of code: new optional argument, no backwards compatibility issues
Individual IDs and observation numbers included in output of apollo_bootstrap
Functions affected: apollo_bootstrap
Detailed description: apollo_bootstrap now writes the indivID and apollo_seq to its file output .
Backwards compatibility of code: Changes to output.
Ability to include constraints in classical estimation
Functions affected: apollo_estimate
Detailed description: apollo_estimate now has an additional optional argument for constraints.
Backwards compatibility of code: New capability.
Fixed a bug where apollo_lcEM was still running when generic parameters were included, and a separate bug with the calculation of the log-likelihood with multiple cores
apollo_estimate with bootstrap
Fixed a bug where apollo_estimate could not run post-estimation bootstrapping when using multiple cores
apollo_basTest
Fixed a bug to prevent apollo_basTest from running when the better fitting model has fewer parameters
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.2.1 (28 October 2020)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
None apollo_lcEM
Fixed bugs where apollo_lcEM could not be used with multiple cores, or when not additionally computing the covariance matrix
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.2.0 (19 October 2020)
Changes to Apollo code:
Major improvements to efficiency, stability and reporting of user errors.
Ben-Akiva & Swait test added
Functions affected: apollo_basTest
Detailed description: the user can now perform the Ben-Akiva & Swait test
Backwards compatibility of code: new function from version 0.2.0 onwards
New outputs for bootstrap, and changes to storage of repetitions
Functions affected: apollo_bootstrap
Detailed description: apollo_bootstrap now returns a list which contains two components, namely a list of estimated parameters and likelihood function in each repetition, and the covariance matrix. In addition, when called an additional time, the function will always add new repetitions to old files, if they exist (it wont complete" the requested number).
Backwards compatibility of code: format of output has changed for post-processingno backwards compatibility issues
apollo_inputs is no longer automatically updated when calling post-processing functions
Functions affected: apollo_conditionals, apollo_lcConditionals, apollo_lcUnconditionals, apollo_llCalc, apollo_prediction, apollo_unconditionals
Detailed description: In previous versions, apollo_inputs would be updated when calling post-processing functions. Now Apollo instead checks if any inputs have changed and alerts the user to revalidate apollo_inputs.
Backwards compatibility of code: examples where changes to the data were made post estimation require a call to apollo_validateInputs
Model description added to output of apollo_combineResults
Functions affected: apollo_combineResults
Detailed description: The csv file produced by apollo_combineResults now includes the model description defined in apollo_control by the user
Backwards compatibility of code: Ouput changed, but no backwards compatibility issues
Estimation time split into separate components in output
Functions affected: apollo_modelOuptut, whether using apollo_estimate or apollo_estimateHB
Detailed description: The time taken by apollo_modelOuptut and apollo_estimate is now split into pre-processing, estimation, and post-processing time
Backwards compatibility of code: Ouput changed, but no backwards compatibility issues
apollo_fitsTest uses log-likelihood instead of probabilities
Functions affected: apollo_fitsTest
Detailed description: In previous versions of Apollo, the function apollo_fitsTest used the probability of correct prediction, which was not appropriate for non-discrete choice models and also not for multi-component models. The function now uses the log-likelihood instead. The function also only does this for the overall model, i.e. no longer allowing the user to look separately at subcomponents of a joint model.
Backwards compatibility of code: Ouput changed.
ID included in outputs of apollo_lcConditionals
Functions affected: apollo_lcConditionals
Detailed description: The individual-specific value for apollo_control$indivID is now included as the first column of the output of apollo_lcConditionals
Backwards compatibility of code: Ouput changed.
New function for EM algorithm for latent class models
Functions affected: apollo_lcEM
Detailed description: Function for automatically using the EM algorithm for latent class models rather than requiring the user to code this for a specific model
Backwards compatibility of code: New function. Users interested in how to code this manually are referred to earlier manuals.
New function for EM algorithm for mixed logit
Functions affected: apollo_mixEM
Detailed description: Function for automatically using the EM algorithm for mixed logit models with a full covariance matrix and all parameters being random
Backwards compatibility of code: New function. Users interested in how to code this manually are referred to earlier manuals.
New input options for likelihood ratio test, and enhanced output
Functions affected: apollo_lrTest
Detailed description: Apollo now allows the user to apply a likelihood ratio test using outputs from two models that are stored in memory (rather than one model needing to have been saved to disk). The restricted model also no longer needs to be given first, as Apollo will determine the order of the two models. The apollo_llTest function now also prints the likelihoods of each model as well as their difference.
Backwards compatibility of code: No backwards compatibility issues.
User can specify number of replications to use in MDCEV forecasting
Functions affected: apollo_mdcev and apollo_mdcev
Detailed description: The user can specify the number of replications using the optional argument nRep
Backwards compatibility of code: No backwards compatibility issues.
New optional settings for model output
Functions affected: apollo_modelOutput and apollo_saveOutput
Detailed description: The setting printPVal can now take three values: 0 (no p-vals), 1 (one-sided), or 2 (two-sided). The setting printDiagnostics was split in two settings: printDataReport (logical) to print the summary of the dependent variable, and printModelStructure (logical) to print data on nesting structures. A new setting printFunctions is included to print a copy of apollo_probabilities, apollo_control, scaling (for estimation and Hessian), Hessian routines
attempted, apollo_lcPars and apollo_randCoeff.
Backwards compatibility of code: No backwards compatibility issues as old input still accepted and new inputs are optional.
Changes to storage of repetitions for out of sample prediction
Functions affected: apollo_outOfSample
Detailed description: When called an additional time apollo_outOfSample will always add new repetitions to old files, if they exist (it wont complete" the requested number).
Backwards compatibility of code: format of output has changed for post-processingno backwards compatibility issues
Improved output for predictions
Functions affected: apollo_prediction
Detailed description: A summary of the predictions are printed in a nice way, with special handling of MDCEV models. Automatic creation of confidence intervals when using repeated sampling.
Backwards compatibility of code: Output changed
Data no longer gets sorted by ID
Functions affected: apollo_validateData
Detailed description: Apollo no longer sorts the data by apollo_control$ID. Sorting is not required by the user either, but all observations from same individual need to be contiguous in the data.
Backwards compatibility of code: Apollo will now ask the user to group together data for the same individual. Some older models may thus require adjustment to the data.
Allow working in logs for cross-sectional data
Functions affected: apollo_validateInputs
Detailed description: Previous versions of Apollo allowed the use of apollo_control$workInLogs only with panel data.
Backwards compatibility of code: No backwards compatibility issues.
Changes to reserved names
Functions affected: apollo_validateInputs
Detailed description: The restrictions imposed in version 0.1.1 for reserved names have been relaxed, and replaced by a check that no names from apollo_beta, apollo_randCoeff, database, apollo_draws or apollo_lcPars are redefined elsewhere.
Backwards compatibility of code: Possible changes needed to old model files.
Ability to use a subset of model components in apollo_combineModels
Functions affected: apollo_combineModels
Detailed description: The user can now specify a subset of model components to multiply.
Backwards compatibility of code: New optional argument.
Detailed description: Uses bootstrap standard errors.
Backwards compatibility of examples: This functionality was not supported in previous versions.
Examples affected: apollo_example_3.r and apollo_example_22.r
Detailed description: Function apollo_validateInputs is called before every apollo_prediction to update database inside apollo_inputs.
Backwards compatibility of examples: If apollo_validateInputs is not called before prediction (as in previous versions), then the prediction will not change, even if the version of database in the Global Environment changes.
Examples affected: apollo_example_6.r
Detailed description: Added Ben-Akiva and Swait test, i.e. a call to function apollo_basTest.
Backwards compatibility of examples: apollo_basTest was not implemented in previous version, so it will fail.
Examples affected: apollo_example_11.r and apollo_example_12.r
Detailed description: Name of scale parameter is now sigma.
Backwards compatibility of examples: Previous versions did not allow user defined variables to be called sigma, so the example will fail in previous versions.
Examples affected: apollo_example_11.r
Detailed description: Removed line colMeans(predictions_base). This is no longer necessary as apollo_prediction now prints an aggregate summary of the predicted values.
Backwards compatibility of examples: The aggregate summary of the prediction will not be shown in previous versions.
Examples affected: apollo_example_14.r
Detailed description: This example now uses 4-core multithreading for estimation.
Backwards compatibility of examples: No issues.
Examples affected: apollo_example_18.r, apollo_example_20.r, apollo_example_27.r and apollo_example_28.r
Detailed description: When looping over latent classes inside apollo_probabilities, the total number of classes is not hard-coded any more. Instead, the number of classes is obtained as the length of pi_values (part of the return of apollo_lcPars())
Backwards compatibility of examples: No issues.
Examples affected: apollo_example_20.r
Detailed description: Dropping first column of conditionals as this now includes the ID.
Backwards compatibility of examples: Change needed from v.0.2.0. onwards.
Examples affected: apollo_example_27.r and apollo_example_28.r
Detailed description: EM estimation is now achieved using apollo_lcEM.
Backwards compatibility of examples: This example will not run in Apollo v0.1.1 or earlier, as function apollo_lcEM does not exist in those versions.
Examples affected: apollo_example_29.r
Detailed description: EM estimation is now achieved using apollo_mixEM.
Backwards compatibility of examples: This example will not run in Apollo v0.1.1 or earlier, as function apollo_mixEM does not exist in those versions.
Fixed a bug where apollo_choiceAnalysis failed when an entry in choiceAnalysis_settings$explanators was empty
Seed for apollo_makeDraws
Fixed a bug where this function was looking for apollo_control$seed_draws instead of apollo_control$seed
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.1.1 (15 September 2020)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
Additional checks on draws
Functions affected: all functions with mixing
Detailed description: Apollo now ensures that intra-individual draws are only used in the presence of multiple observations per individual.
Backwards compatibility of code: no backwards compatibility issues
Additional checks for exploded logit
Functions affected: apollo_el
Detailed description: The apollo_el now ensures that no alternative is chosen more than once across stages and ensures that any obsolete stages have the choice variable coded as -1.
Backwards compatibility of code: no backwards compatibility issues
Parameter specific constraints in HB estimation can now use names of parameters
Functions affected: apollo_estimate with apollo_control$HB==TRUE
Detailed description: the user can now use names of parameters when creating constraints for individual parameters in HB estimation rather than relying on the numeric coding from RSGHB
Backwards compatibility of code: no backwards compatibility issues for existing functions as old format for input still permitted
Additional flexibility for thresholds in ordered logit and ordered probit
Functions affected: apollo_ol and apollo_op
Detailed description: The thresholds for ordered logit and ordered logit are now given as a list, with one entry per threshold, thus allowing the user to have thresholds varying across observations/individuals, with possible additional random heterogeneity.
Backwards compatibility of code: no backwards compatibility issues as the function can still be called with the thresholds as a simple vector
Check for use of reserved names
Functions affected: apollo_validateInputs
Detailed description: For internal consistency, some core names, such as alternatives, avail and sigma are now protected and cannot be used in the data, apollo_beta, apollo_lcPars and apollo_randCoeff.
Backwards compatibility of code: backwards compatibility for some model files, but can be easily addressed by changing names
Detailed description: Uses new specification of thresholds as a list for apollo_ol
Backwards compatibility of examples: old format still accepted
Examples affected: apollo_example_11.r, apollo_example_12.r and apollo_example_17.r
Detailed description: sigma replaced by sig to avoid protected names issue
Backwards compatibility of examples: change required for v 0.1.1 onwards
Fixed a bug where Apollo allowed the use of apollo_conditionals despite having apollo_control$workInLogs==TRUE. This led to a failure as the probabilities are not available at the draw level when working in logs. This functionality is consequently not available now.
apollo_estimate with HB and constraints
Fixed a bug that led to a failure if a constraint was imposed on the final element of apollo_beta.
apollo_estimate with apollo_control$workInLogs==TRUE
Fixed a bug that led to a failure if the probabilities were zero with some draws. Also fixed a bug when using latent class models with apollo_control$workInLogs==TRUE which led to a bias in the calculation of probabilities.
apollo_ol and apollo_op
Fixed a bug that led to a failure when using a response variable with fewer or more than 5 levels
apollo_sharesTest
Fixed a bug that led to a failure when using apollo_sharesTest with sharesTest_settings$subsamples==NA and when using rows inside the model
apollo_inputs$apollo_control
Fixed a bug to ensure that when apollo_control is used by a function, it is fetched from apollo_inputs$apollo_control, making sure that when debugging, the correct (i.e. processed) apollo_control is used.
apollo_mdcev
Fixed a bug that led to an erroneous error message and halt to estimation with MDCEV models when using the mdcev_settings$minConsumption setting.
LL(0) with some models using random coefficients
Fixed a bug that led to incorrect LL(0) for some models using random coefficients, notably for latent class models with continuous random coefficients in the class allocation model.
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.1.0 (16 March 2020)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
R version requirement changed to 3.6.0
Functions affected: all of Apollo
Detailed description: users running Apollo version 0.1.0 require at a minimum R version 3.6.0
Backwards compatibility of code: no changes to actual functions
Improved error reporting and printing
Functions affected: majority of functions
Detailed description: warnings are now generally displayed at the point they apply rather than after estimation. In addition, numerous new checks have been implemented for many of the functions.
Backwards compatibility of code: no backwards compatibility issues
Referring to database inside apollo_probabilties no longer allowed
Functions affected: all functions that call apollo_probabilties
Detailed description: the user is not allowed to refer to database by name inside apollo_probabilties. There is no reason for doing so as the database is attached and all elements therein can be referred to directly
Backwards compatibility of code: this should not affect any users. The only requirement is to now use the get function when attempting to retrieve an object whose name is put together via paste0
Can define names for individual model components
Functions affected: all existing functions for models, i.e. apollo_mnl etc
Detailed description: the user can now include an optional additional argument componentName in the settings for individual models. This is then used in the reporting of outputs as well as in any error messages
Backwards compatibility of code: no backwards compatibility issues
Tests for zero probabilities at starting values for individual model components
Functions affected: all existing functions for models, i.e. apollo_mnl etc
Detailed description: unless apollo_control$noValidation==TRUE, Apollo now checks the likelihood of individual model components in addition to the overall model and prints a warning if probabilities are zero for some individuals while estimation is not started if probabilities are zero for all. This is relevant for latent class models, where it is permissable to have zero probabilities for some individuals in some classes, but where initial zero probabilities for all
individuals in a class are likely to highlight problems.
Backwards compatibility of code: no backwards compatibility issues
Ability to sort results by date
Functions affected: apollo_combineResults
Detailed description: an additional option sortByDate has been included. When set to TRUE, the models in the summary file will be sorted by the date when the model was estimated (default set to TRUE)
Backwards compatibility of code: no backwards compatibility issues
Improved memory usage with multi-core estimation
Functions affected: apollo_estimate
Detailed description: Memory requirements for multi-core estimation have been reduced substantially compared to previous versions
Backwards compatibility of code: no backwards compatibility issues
Constraints in HB estimation can now use names of parameters
Functions affected: apollo_estimate with apollo_control$HB==TRUE
Detailed description: the user can now use names of parameters when creating constraints for HB estimation rather than relying on the numeric coding from RSGHB
Backwards compatibility of code: no backwards compatibility issues for existing functions as old format for input still permitted
Smallest absolute eigenvalue of Hessian reported
Functions affected: apollo_estimate, apollo_modelOutput, apollo_saveOutput
Detailed description: Apollo reports the eigenvalue of the Hessian that is closest to zero. Small values can indicate convergence issues. A special warning message is displayed if some of the eigenvalues are positive.
Backwards compatibility of code: no backwards compatibility issues
Check whether class allocation probabilities for latent class sum to 1
Functions affected: apollo_lc
Detailed description: New check to ensure that class alloaction probabilities for latent class sum to 1
Backwards compatibility of code: no backwards compatibility issues
Calculation of LL(0)
Functions affected: apollo_modelOutput and apollo_saveOutput
Detailed description: The calculation of the log-likelihood at zero has been improved for some models, as has the reporting of it. Where this measure does not apply, Apollo now reports “Not applicable” instead of “NA”
Backwards compatibility of code: no backwards compatibility issues
Ordered probit added
Functions affected: apollo_op
Detailed description: the user can now use ordered probit models via the function apollo_op
Backwards compatibility of code: no backwards compatibility issues
Out of sample testing can add to existing runs
Functions affected: apollo_outOfSample
Detailed description: apollo_outOfSample checks whether output files already exists and adds to those if the number of runs requested is larger than what is already stored in these files
Backwards compatibility of code: no backwards compatibility issues
Prevent use of some functions for HB models
Functions affected: apollo_panelProd, apollo_avgInterdraws, apollo_avgIntraDraws, apollo_deltaMethod, apollo_conditionals, apollo_unconditionals, apollo_lcConditionals, apollo_lcUnconditionals
Detailed description: Many of the Apollo functions are for classical estimation only, and their use previously led to failures. Their use is now prevented when apollo_control$HB==TRUE.
Backwards compatibility of code: the call to these functions was previously ignored and will now lead to a failure in any files they are still included in. The appropriate lines need commenting out.
Inputs changed for apollo_prediction and added ability to calculate standard errors
Functions affected: apollo_prediction
Detailed description: the apollo_prediction function now takes prediction_settings as an input, where this is the new location for including modelComponent. In addition, an optional setting called runs has been included that computes standard errors across multiple prediction runs based on different draws from the estimates and covariance matrix for the model parameters
Backwards compatibility of code: no backwards compatibility issues for existing functions as old format for input still permitted
Output files no longer overwritten
Functions affected: apollo_saveOutputs
Detailed description: the apollo_saveOutput function now checks whether output files for the model already exists and changes their names (by including OLD in the name) rather than overwritting them
Backwards compatibility of code: no backwards compatibility issues
Output file for starting value search simplified
Functions affected: apollo_searchStart
Detailed description: The output file for apollo_searchStart was simplified from v0.0.9 to v0.1.0. Now it only records starting candidate values, and their log-likelihoods throughout the stages, but not their values at each stage, as it used to.
Backwards compatibility of code: no backwards compatibility issues
Subsetting of data when some variables are factors
Functions affected: all functions making use of the database
Detailed description: If a dataset contains factors, the use of subsetting of the data in R would still retain levels that no longer apply. This is a feature of R which can have unintended consequences and we thus eliminate any missing levels.
Backwards compatibility of code: no backwards compatibility issues
Detailed description: include calculation of standard errors for forecasts
Backwards compatibility of examples: affected part only works from version 0.1.0 onwards
Examples affected: apollo_example_3 and apollo_example_26
Detailed description: use cost increase by 1% instead of 10% for calculating elasticities
Backwards compatibility of examples: no backwards compatibility issues
Examples affected: apollo_example_5
Detailed description: apollo_example_5 no longer reads in the results from apollo_example_4 as starting values as this woudl have implied an inconsistent initial nesting structure
Backwards compatibility of examples: no backwards compatibility issues
Examples affected: apollo_example_18, apollo_example_19, apollo_example_20, apollo_example_22, apollo_example_27 and apollo_example_28
Detailed description: componentName added to class specific models
Backwards compatibility of examples: setting ignored in earlier versions
Examples affected: apollo_example_22
Detailed description: in the use of apollo_prediction, modelComponent is now included in prediction_settings rather than as a direct input
Backwards compatibility of examples: affected part only works from version 0.1.0 onwards
Examples affected: apollo_example_28
Detailed description: included apollo_probabilities as an argument for apollo_unconditionals
Backwards compatibility of examples: this is a bug fix that ensures the example now runs correctly
Adding additional bootstrap runs with the same seed now ensures that new draws are used rather than adding the same results that already exist.
apollo_combineResults
When combineResults_settings$modelNames was not provided, other settings were ignored
apollo_estimate
Earlier versions still performed model validation even if apollo_control$noValidation==TRUE
apollo_lc
The pre-estimation diagnostic tests would fail in case the starting values were the same for multiple classes in a latent class model
apollo_lcConditionals
Conditionals from latent class used to report one row per observation, while they should have reported one row per individual
apollo_mdcev
When the rows option was used, any pre-estimation checks still included all rows in the data. In addition, some failures could occur in estimation.
apollo_prediction
Predictions from latent class were missing the names of the alternatives in the output
apollo_searchStart
Multiple bugs have been corrected. In previous versions, the function would ignore converged candidates and would pick the wrong candidate as “best”
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.0.9 (23 October 2019)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
Additional diagnostic message for HB estimation
Functions affected: apollo_estimate
Detailed description: the RSGHB package used for Bayesian estimation left censors likelihood values at the individual level to avoid numerical issues. This has the undesired side effect of mis-specified models still running, and a warning message is now displayed when censoring has been used
Backwards compatibility of code: function called in the same way
Pre-estimation tests to ensure all parameters affect likelihood function
Functions affected: apollo_estimate
Detailed description: unless apollo_control$noDiagnostics==TRUE, a pre-estimation check is used to ensure that there are no parameters in apollo_beta for which changes do not lead to changes in the model likelihood
Backwards compatibility of code: function called in the same way
apollo_deltaMethod
This function had a small error in the calculation for standard errors for logistic transforms
apollo_estimate with HB and only non-random parameters
HB estimation failed in earlier versions for models without any random parameters if using scaling
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.0.8 (9 September 2019)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
Bootstrap estimation added
Functions affected: apollo_bootstrap, apollo_estimate
Detailed description: the user can now perform bootstrap estimation. This can also be called directly with apollo_estimate during estimation
Backwards compatibility of code: new function from version 0.0.8 onwards, new optional arguments for apollo_estimate, but function called in the same way
Allow user to use subset of rows for analysis of choices
Functions affected: apollo_choiceAnalysis
Detailed description: An additional rows argument can be entered into choiceAnalysis_settings.
Backwards compatibility of code: optional argument added from version 0.0.8 onwards, but function called in the same way
Outputs changed for apollo_choiceAnalysis
Functions affected: apollo_choiceAnalysis
Detailed description: outputs changed so that t-test value is reported instead of p-value, and order of outputs is changed
Backwards compatibility of code: outputs changed from version 0.0.8 onwards, but function called in the same way
Allow user to change name and location of outside good in MDCEV and MDCNEV
Functions affected: apollo_mdcev and apollo_mdcnev
Detailed description: An additional outside argument can be entered into mdcev_settings and mdcnev_settings with the name of the outside good which can now differ from outside. It also no longer needs to be in first position in the list of alternatives.
Backwards compatibility of code: optional argument added from version 0.0.8 onwards, but function called in the same way
No need to define superfluous gamma for outside good in MDCEV and MDCNEV
Functions affected: apollo_mdcev and apollo_mdcnev
Detailed description: The user no longer needs to create a gamma term for the outside good.
Backwards compatibility of code: function called in the same way
Chosen unavailable alternatives have a likelihood of zero
Functions affected: apollo_mnl, apollo_mdcev, apollo_mdcnev
Detailed description: MNL, MDCEV and MDCNEV now return a likelihood equal to zero for chosen alternatives that are not available. This change is only relevant if apollo_control$noValidation is TRUE.
Backwards compatibility of code: new likelihood values for unavailable chosen alternatives on MNL, MDCEV and MDCNEV models from version 0.0.8 onwards
Allow user to specify number of outliers to report
Functions affected: apollo_modelOutput, apollo_saveOutput
Detailed description: In addition to specifying TRUE/FALSE for printOutliers, the user can provide the number of outliers to report (instead of the default of 20).
Backwards compatibility of code: optional argument added from version 0.0.8 onwards, but function called in the same way
Ability to define estimation/validation subsets for apollo_outOfSample
Functions affected: apollo_outOfSample
Detailed description: the user can now provide a matrix or data.frame describing which observations are to be used in the estimation and validation subsets
Backwards compatibility of code: optional argument added from version 0.0.8 onwards, but function called in the same way
Individual IDs and choice scenario numbers added in predictions
Functions affected: apollo_prediction
Detailed description: The output from apollo_prediction now includes the IDs and choice observation numbers as the first two columns.
Backwards compatibility of code: function called in the same way
Examples affected: apollo_example_3.r, apollo_example_11.r, apollo_example_13.r, apollo_example_22.r, apollo_example_24.r, apollo_example_25.r, apollo_example_26.r
Detailed description: apollo_prediction now includes the IDs and observation numbers as the first two columns, meaning some output is shifted.
Backwards compatibility of examples: use of outputs needs adjusting to reflect change in columns
This function failed in earlier versions when using only a single model
apollo_firstRow
This function mistakenly replicated the first row for each person Tn times
apollo_estimate with scaling and HB
HB estimation failed in earlier versions for models without any random parameters
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.0.7 (8 May 2019)
Changes to Apollo code:
Minor improvements to efficiency, stability and reporting of user errors.
Inputs changed for apollo_choiceAnalysis
Functions affected: apollo_choiceAnalysis
Detailed description: inputs changed so function can be called prior to apollo_validateInputs
Backwards compatibility of code: function call changed from version 0.0.7 onwards
Constraints for classical estimation
Functions affected: apollo_estimate
Detailed description: Apollo now allows the user to include a list called constraints in estimate_settings for use with BFGS for classical model estimation.
Backwards compatibility of code: no backwards compatibility issues for existing functions
Scaling of parameters during model estimation
Functions affected: apollo_estimate
Detailed description: scaling of model parameters can be used during estimation
Backwards compatibility of code: no backwards compatibility issues for existing functions
Validation output
Functions affected: apollo_estimate
Detailed description: Apollo no longer reports that all pre-estimation checks were passed for a model component and instead only reports if there are an issues.
Backwards compatibility of code: no backwards compatibility issues for existing functions
Bayesian estimation produces model$estimate
Functions affected: apollo_estimate, apollo_prediction, apollo_llCalc
Detailed description: until version 0.0.6, Bayesian estimation in Apollo did not produce a model$estimate output. We have retained the various existing outputs, but in addition, model$estimate is now produced, combining non-random parameters with individual specific posteriors for random parameters. This now allows the user to use apollo_prediction and apollo_llCalc on such outputs, where care is of course required in interpretation of outputs based on posterior
means.
Backwards compatibility of code: no backwards compatibility issues for existing functions
Detailed description: Use of apollo_choiceAnalysis added
Backwards compatibility of examples: affected part only works from version 0.0.7 onwards
Examples affected: apollo_example_12.r
Detailed description: Scaling in estimation implemented
Backwards compatibility of examples: only works from version 0.0.7 onwards
Examples affected: apollo_example_26.r
Detailed description: HB prediction component added
Backwards compatibility of examples: affected part only works from version 0.0.7 onwards
Bug fixes:
apollo_speedTest
This function was unintentionally hidden from users in previous versions
GO TO HISTORY OF APOLLO VERSIONS AND CHANGES
GO TO TOP OF PAGE
Version 0.0.6 (13 March 2019)
This is the first fully functioning release of Apollo.