apollo_varcov: Calculates variance-covariance matrix of an Apollo model

In apollo: Tools for Choice Model Estimation and Application

Calculates variance-covariance matrix of an Apollo model

Description

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.

Usage

apollo_varcov(apollo_beta, apollo_fixed, varcov_settings)

Arguments

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: apollo_logLike, apollo_grad or apollo_inputs together with apollo_probabilities. apollo_grad: Function to calculate the gradient of the model, as returned by apollo_makeGrad. apollo_hessian: Function to calculate the hessian of the model, as returned by apollo_makeHessian. apollo_inputs: List grouping most common inputs. Created by function apollo_validateInputs. apollo_logLike: Function to calculate the log-likelihood of the model, as returned by apollo_makeLogLike. apollo_probabilities: apollo_probabilities 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 "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL". BHHHhessian: Matrix. Optional input, providing the BHHH matrix so it does not get recalculated. hessianRoutine: Character. Name of routine used to calculate the Hessian. Valid values are "analytic", "numDeriv", "maxLik" or "none" to avoid estimating the Hessian and covariance matrix. numDeriv_method: Character. Method used for numerical differentiation. Can be "Richardson" or "simple", Only used if analytic gradients are available. See argument method in grad for more details. 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. scaleBeta: Logical. If TRUE (default), parameters are scaled by their own value before calculating the Hessian to increase numerical stability. However, the output is de-scaled, so they are in the same scale as the apollo_beta argument.

Details

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).

Value

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.

apollo documentation built on Nov. 5, 2025, 5:07 p.m.