naginterfaces.library.correg.mixeff_​hier_​reml

naginterfaces.library.correg.mixeff_hier_reml(vpr, gamma, comm, iopt=None, ropt=None, io_manager=None)[source]

mixeff_hier_reml fits a multi-level linear mixed effects regression model using restricted maximum likelihood (REML). Prior to calling mixeff_hier_reml the initialization function mixeff_hier_init() must be called.

Deprecated since version 27.0.0.0: mixeff_hier_reml is deprecated. Please use lmm_fit() instead. See also the Replacement Calls document.

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

https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/g02/g02jdf.html

Parameters
vprint, array-like, shape

A vector of flags indicating the mapping between the random variables specified in and the variance components, . See Further Comments for more details.

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

ioptNone or int, array-like, shape , optional

Options passed to the optimization function.

By default mixeff_hier_reml fits the specified model using a modified Newton optimization algorithm as implemented in opt.bounds_mod_deriv2_comp. In some cases, where the calculation of the derivatives is computationally expensive it may be more efficient to use a sequential QP algorithm.

The sequential QP algorithm as implemented in opt.nlp1_solve can be chosen by setting .

If or , then the modified Newton algorithm will be used.

Different options are available depending on the optimization function used.

In all cases, using a value of will cause the default value to be used.

In addition only the first values of are used, so for example, if only the first element of needs changing and default values for all other options are sufficient can be set to .

The following table lists the association between elements of and arguments in the optimizer when the modified Newton algorithm is being used.

Description

Equivalent argument

Default Value

Number of iterations

Unit number for monitoring information

n/a

The advisory unit number

Print options ( print)

n/a

(no printing performed)

Frequency that monitoring information is printed

Optimizer used

n/a

n/a

If requested, monitoring information is displayed in a similar format to that given by the modified Newton optimizer.

The following table lists the association between elements of and options in the optimizer when the sequential QP algorithm is being used.

Description

Equivalent option

Default Value

Number of iterations

‘Major Iteration Limit’

Unit number for monitoring information

n/a

The advisory unit number

Print options ( print, otherwise no print)

‘List’/’Nolist’

(no printing performed)

Frequency that monitoring information is printed

‘Major Print Level’

Optimizer used

n/a

n/a

Number of minor iterations

‘Minor Iteration Limit’

Frequency that additional monitoring information is printed

‘Minor Print Level’

If , default values are used for all options and is not referenced.

roptNone or float, array-like, shape , optional

Options passed to the optimization function.

Different options are available depending on the optimization function used.

In all cases, using a value of will cause the default value to be used.

In addition only the first values of are used, so for example, if only the first element of needs changing and default values for all other options are sufficient can be set to .

The following table lists the association between elements of and arguments in the optimizer when the modified Newton algorithm is being used.

Description

Equivalent argument

Default Value

Sweep tolerance

n/a

Lower bound for

n/a

Upper bound for

n/a

Accuracy of linear minimizations

Accuracy to which solution is required

Initial distance from solution

The following table lists the association between elements of and options in the optimizer when the sequential QP algorithm is being used.

Description

Equivalent option

Default Value

Sweep tolerance

n/a

Lower bound for

n/a

Upper bound for

n/a

Line search tolerance

‘Line Search Tolerance’

Optimality tolerance

‘Optimality Tolerance’

where is the machine precision returned by machine.precision and denotes the diagonal element of .

If , then default values are used for all options and may be set to None.

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 .

effnint

Effective number of observations. If no weights were supplied to mixeff_hier_init() or all supplied weights were 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, then .

lnlikefloat

where is the log of the restricted maximum likelihood calculated at , the estimated variance components returned in .

estidint, ndarray, shape

An array describing the parameter estimates returned in . The first columns of describe the parameter estimates for the random effects and the last columns the parameter estimates for the fixed effects.

For fixed effects:

for

if contains the parameter estimate for the intercept, then

if contains the parameter estimate for the th level of the th fixed variable, that is the vector of values held in the th column of when then

if the th variable is continuous or binary, that is , ;

any remaining rows of the th column of are set to .

For random effects:

let

denote the number of random variables in the th random statement, that is ;

denote the th random variable from the th random statement, that is the vector of values held in the th column of when ;

denote the number of subject variables in the th random statement, that is ;

denote the th subject variable from the th random statement, that is the vector of values held in the th column of when ;

denote the number of levels for , that is ;

then

for , if contains the parameter estimate for the th level of when , for and , i.e., is a valid value for the th subject variable, then

if the parameter being estimated is for the intercept, then ;

if the th variable is continuous, or binary, that is , then ;

the remaining rows of the th column of are set to .

In some situations, certain combinations of variables are never observed.

In such circumstances all elements of the th row of are set to .

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, . The order of these estimates are described by the argument.

sefloat, ndarray, shape

The standard errors of the parameter estimates given in .

czzfloat, ndarray, shape

If , then 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 subject variable, the next columns the part corresponding to the second level of the overall subject variable etc.

cxxfloat, ndarray, shape

holds the lower triangular portion of the matrix , where is the estimated value of .

cxzfloat, ndarray, shape

If , then holds 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 subject variable, the next columns the part corresponding to the second level of the overall subject variable etc.

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: or .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, [‘iopts’] has not been initialized correctly.

(errno )

On entry, at least one value of i, for , does not appear in .

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

mixeff_hier_reml 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 , mixeff_hier_reml uses an iterative process to estimate . Due to the iterative nature of the estimation a set of initial values, , for is required. mixeff_hier_reml 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).

mixeff_hier_reml fits the model by maximizing the restricted log-likelihood function:

where

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