naginterfaces.library.correg.lmm_fit¶
- naginterfaces.library.correg.lmm_fit(hlmm, gamma, comm, wantc=False, io_manager=None)[source]¶
lmm_fit
fits a multi-level linear mixed effects regression model using restricted maximum likelihood (REML) or maximum likelihood (ML). Prior to callinglmm_fit
the initialization functionlmm_init()
must be called.For full information please refer to the NAG Library document for g02jh
https://www.nag.com/numeric/nl/nagdoc_29/flhtml/g02/g02jhf.html
- Parameters
- hlmmHandle
A G22 handle to the internal data structure containing a description of the required model as returned in by
lmm_init()
.- gammafloat, array-like, shape
Holds the initial values of the variance components, , with the initial value for , for .
If , the remaining elements of are ignored and the initial values for the variance components are estimated from the data using MIVQUE0.
- commdict, communication object, modified in place
Communication structure.
This argument must have been initialized by a prior call to
lmm_init()
.- wantcbool, optional
Flag indicating whether the arrays , and are required.
- io_managerFileObjManager, optional
Manager for I/O in this routine.
- Returns
- gammafloat, ndarray, shape
, for , holds the final estimate of and holds the final estimate for .
Labels for the variance components can be obtained using
blgm.lm_submodel
.- effnint
Effective number of observations. If there are no weights, or all weights are nonzero, .
- rnkxint
The rank of the design matrix, , for the fixed effects.
- ncovint
Number of variance components not estimated to be zero. If none of the variance components are estimated to be zero, .
- lnlikefloat
where is the log of the restricted maximum likelihood calculated at , the estimated variance components returned in .
- bfloat, ndarray, shape
The parameter estimates, with the first elements of containing the parameter estimates for the random effects, , and the remaining elements containing the parameter estimates for the fixed effects, .
Labels for the parameter estimates can be obtained using
blgm.lm_submodel
.- sefloat, ndarray, shape
The standard errors of the parameter estimates given in .
- czzNone or float, ndarray, shape
If , holds the lower triangular portion of the matrix , where and are the estimates of and respectively.
If , then holds this matrix in compressed form, with the first columns holding the part of the matrix corresponding to the first level of the overall random subject variable, the next columns holding the part of the matrix corresponding to the second level of the overall random subject variable etc.
If , is returned as None.
- cxxNone or float, ndarray, shape
If , holds the lower triangular portion of the matrix , where is the estimated value of .
If , then holds this matrix in compressed form, with the first columns holding the part of the matrix corresponding to the first level of the overall fixed subject variable, the next columns holding the part of the matrix corresponding to the second level of the overall fixed subject variable, etc.
If , is returned as None.
- cxzNone or float, ndarray, shape
holds the matrix , where and are the estimates of and respectively.
If , is returned as None.
- Raises
- NagValueError
- (errno )
has not been initialized or is corrupt.
- (errno )
is not a G22 handle as generated by
lmm_init()
.- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: or .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, the communication arrays, [‘iopts’] and [‘opts’], have not been initialized correctly.
- Warns
- NagAlgorithmicWarning
- (errno )
Optimal solution found, but requested accuracy not achieved.
- (errno )
Too many major iterations.
- (errno )
Current point cannot be improved upon.
- (errno )
At least one negative estimate for was obtained. All negative estimates have been set to zero.
- Notes
lmm_fit
fits a model of the form:where
is a vector of observations on the dependent variable,
is a known design matrix for the fixed independent variables,
is a vector of length of unknown fixed effects,
is a known design matrix for the random independent variables,
is a vector of length of unknown random effects,
and
is a vector of length of unknown random errors.
Both and are assumed to have a Gaussian distribution with expectation zero and variance/covariance matrix defined by
where , is the identity matrix and is a diagonal matrix. It is assumed that the random variables, , can be subdivided into groups with each group being identically distributed with expectation zero and variance . The diagonal elements of matrix , therefore, take one of the values , depending on which group the associated random variable belongs to.
The model, therefore, contains three sets of unknowns: the fixed effects , the random effects and a vector of variance components , where . Rather than working directly with ,
lmm_fit
uses an iterative process to estimate . Due to the iterative nature of the estimation a set of initial values, , for is required.lmm_fit
allows these initial values either to be supplied by you or calculated from the data using the minimum variance quadratic unbiased estimators (MIVQUE0) suggested by Rao (1972).lmm_fit
fits the model by maximizing the restricted log-likelihood function:or the log-likelihood function:
where
By default the restricted log-likelihood function is used, the log-likelihood function can be chosen through the option ‘Solver’ as detailed in the documentation for
lmm_init()
.Once the final estimates for have been obtained, the value of is given by
Case weights, , can be incorporated into the model by replacing and with and respectively, for a diagonal weight matrix .
The log-likelihood, , is calculated using the sweep algorithm detailed in Wolfinger et al. (1994).
- References
Goodnight, J H, 1979, A tutorial on the SWEEP operator, The American Statistician (33(3)), 149–158
Harville, D A, 1977, Maximum likelihood approaches to variance component estimation and to related problems, JASA (72), 320–340
Rao, C R, 1972, Estimation of variance and covariance components in a linear model, J. Am. Stat. Assoc. (67), 112–115
Stroup, W W, 1989, Predictable functions and prediction space in the mixed model procedure, Applications of Mixed Models in Agriculture and Related Disciplines (Southern Cooperative Series Bulletin No. 343), 39–48
Wolfinger, R, Tobias, R and Sall, J, 1994, Computing Gaussian likelihoods and their derivatives for general linear mixed models, SIAM Sci. Statist. Comput. (15), 1294–1310