bgw_mle {bgw}  R Documentation 
bgw_mle
Description
Performs maximum likelihood estimation (MLE) for the userprovided model
defined in bgw_calcR
.
Usage
bgw_mle(calcR, betaStart, calcJ = NULL, bgw_settings = NULL)
Arguments
calcR 
Function that computes an nvector (R) of model residuals for a pvector of (numeric) parameters beta (the first argument). In this case the residuals are likelihoods (probabilities). (The beta vector can be named or unnamed.) 
betaStart 
Vector of initial starting values for beta. Can be either a named or unnamed vector. 
calcJ 
Function that computes the matrix of partial derivatives of R wrt beta (a.k.a. the Jacobian). If NULL, finitedifference derivatives are used. In matrix form, dim=c(p,n). However, it could be stored as a vector in columnmajor order. 
bgw_settings 
List. Contains control parameters for BGW estimation code. All parameters have default values, so user input is entirely optional.

Details
This function has been written to provide an Rbased interface to Fortran estimation software published in Bunch, Gay and Welsch (1993), "Algorithm 717Subroutines for Maximum Likelihood and QuasiLikelihood Estimation of Parameters in Nonlinear Regression Models," ACM Transactions on Mathematical Software, 19 (1), March 1993, 109130. The letters BGW will be used in various ways to denote the source of the estimation functionality.
A primary motivation was to develop a more efficient maximum likelihood estimation function for use in the Apollo choice modelling package: see http://www.apollochoicemodelling.com/. However, we have adopted a design whereby the BGW package is wholly independent of Apollo, and can be used in a standalone fashion. Note also that the BGW Fortran subroutines are written to support general statistical estimation for an arbitrary objective/criterion function. So, although this version of the package is specifically written for MLE, the package may see future updates that expand the number of estimation options (for, e.g., nonlinear least squares, generalized method of moments, etc.).
Remark: Following the convention in the numerical optimization literature, BGW minimizes the objective function. That is, bgw_mle minimizes the negativeloglikelihood for the model calcR.
Value
model object of class 'bgw_mle'. Output of a bgw maximum likelihood estimation procedure. A list with the following attributes:

betaStart
: Vector of initial starting values. 
bgw_settings
: List. The same as the input argument. 
hasAnalyticGrad
: Logical. Indicates in an analytical gradient calculation was used. If the user has not provided a calcJ function (see input parameter), it is set to FALSE. 
numParams
: Numeric. Number of model parameters used in calcR. 
numResids
: Numeric. Number of independent observations (model residuals) in data set = dimension of calcR output. 
code
: Numeric. Numeric return code from BGW. 
message
: Character. Message statement characterizing termination of MLE search. 
betaStop
: Vector. Value of parameter vector at conclusion of MLE search. See message to determine if beta is a valid estimate. 
finalLL
: Numeric. Value of loglikelihood at betaStop. 
iterations
: Numeric. Number of iterations used in MLE search. In BGW, this is the same as the number of gradient evaluations. 
functionEvals
: Numeric. Number of function evaluations used in MLE search. (This excludes function evaluations used by any finitedifference calculations for the gradient and/or the vcHessian. 
gradient
: Vector. The gradient evaluated at betaStop. 
scaleVec
: Vector. The scaling vector at the conclusion of the MLE search. Note: In the current version, this will be a pvector of 1's (used throughout the search). In future versions, additional scaling options may be implemented. 
estimate
: Vector. MLE parameter vector obtained by BGW. The same as betaStop if a valid convergence condition is achieved. Null otherwise. 
maximum
: Numeric. Final loglikelihood value for a (successful) MLE search. 
hessianMethodAttempted
: String. Requested method for computing vcHessian (from bgw_settings). 
hessianMethodUsed
: String. Method actually used for computing vcHessian (if vcHessian was requested, and if the computation was successful. If not, a message indicating 'no request' or 'singular vcHessian' is provided.) 
vcHessianConditionNumber
: Numeric. Estimated upper bound on reciprocal of Euclidean condition number of vcHessian (if available). Set to 1 if unavailable. 
varcovBGW
: Matrix. pbyp matrix containing estimate of the variancecovariance matrix (if requested and available). 
vcVec
: Vector. Lower triangle of variancecovariance matrix stored in vector form (rowmajor order, if requested and available). 
seBGW
: Vector. Estimated standard errors for parameter estimates (if requested and available). 
tstatBGW
: Vector. Estimated tstatistics (versus 0, if requested and available).