Estimates a model using the likelihood function defined by apollo_probabilities.
apollo_estimate(
apollo_beta,
apollo_fixed,
apollo_probabilities,
apollo_inputs,
estimate_settings = NA
)Named numeric vector. Names and values for parameters.
Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.
Function. Returns probabilities of the model to be estimated. Must receive three arguments:
apollo_beta: Named numeric vector. Names and values of model parameters.
apollo_inputs: List containing options of the model. See apollo_validateInputs.
functionality: Character. Can be either "estimate" (default), "prediction", "validate", "conditionals", "zero_LL", "shares_LL", or "raw".
List grouping most common inputs. Created by function apollo_validateInputs.
List. Options controlling the estimation process.
estimationRoutine: Character. Estimation method. Can take values "bfgs", "bhhh", or "nr".
Used only if apollo_control$HB is FALSE. Default is "bfgs".
maxIterations: Numeric. Maximum number of iterations of the estimation routine before stopping.
Used only if apollo_control$HB is FALSE. Default is 200.
writeIter: Logical. Writes value of the parameters in each iteration to a csv file.
Works only if estimation_routine="bfgs". Default is TRUE.
hessianRoutine: Character. Name of routine used to calculate the Hessian of the loglikelihood
function after estimation. Valid values are "analytic" (default),
"numDeriv" (to use the numeric routine in package numDeric), "maxLik"
(to use the numeric routine in packahe maxLik), and "none" to avoid
estimating the Hessian and the covariance matrix. Only used if apollo_control$HB=FALSE.
printLevel: Higher values render more verbous outputs. Can take values 0, 1, 2 or 3. Ignored if apollo_control$HB is TRUE. Default is 3.
constraints: Character vector. Linear constraints on parameters to estimate. For example
c('b1>0', 'b1 + 2*b2>1'). Only >, < and = can be used.
Inequalities cannot be mixed with equality constraints, e.g. c(b1-b2=0, b2>0)
will fail. All parameter names must be on the left side. Fixed parameters cannot
go into constraints. Alternatively, constraints can be defined as in maxLik.
Constraints can only be used with maximum likelihood estimation and the BFGS routine in particular.
scaling: Named vector. Names of elements should match those in apollo_beta. Optional scaling for parameters.
If provided, for each parameter i, (apollo_beta[i]/scaling[i]) is optimised, but
scaling[i]*(apollo_beta[i]/scaling[i]) is used during estimation. For example, if parameter
b3=10, while b1 and b2 are close to 1, then setting scaling = c(b3=10) can help estimation,
specially the calculation of the Hessian. Reports will still be based on the non-scaled parameters.
maxLik_settings: List. Additional settings for maxLik. See argument control in maxBFGS,
maxBHHH and maxNM for more details. Only used for maximum
likelihood estimation.
numDeriv_settings: List. Additional arguments to the Richardson method used by numDeriv to calculate the Hessian.
See argument method.args in grad for more details.
bootstrapSE: Numeric. Number of bootstrap samples to calculate standard errors. Default is 0, meaning
no bootstrap s.e. will be calculated. Number must zero or a positive integer. Only used
if apollo_control$HB is FALSE.
bootstrapSeed: Numeric scalar (integer). Random number generator seed to generate the bootstrap samples.
Only used if bootstrapSE>0. Default is 24.
silent: Logical. If TRUE, no information is printed to the console during estimation. Default is FALSE.
scaleHessian: Logical. If TRUE, parameters are scaled to 1 for Hessian estimation. Default is TRUE.
scaleAfterConvergence: Logical. Used to increase numerical precision of convergence. If TRUE, parameters are scaled to 1 after convergence, and the estimation is repeated from this new starting values. Results are reported scaled back, so it is a transparent process for the user. Default is TRUE.
model object
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 directory. Writing
can be turned off by setting estimate_settings$writeIter to FALSE, of by using any estimation algorithm
other than BFGS.
By default, final results are not written into a file nor printed into the console, so users must make sure
to call function apollo_modelOutput and/or apollo_saveOutput afterwards.
Users are strongly encouraged to visit 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.