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 calling lmm_fit the initialization function lmm_init() must be called.

For full information please refer to the NAG Library document for g02jh

https://www.nag.com/numeric/nl/nagdoc_27.1/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