naginterfaces.library.correg.mixeff_hier_ml¶
- naginterfaces.library.correg.mixeff_hier_ml(vpr, nvpr, gamma, comm, iopt=None, ropt=None, io_manager=None)[source]¶
mixeff_hier_ml
fits a multi-level linear mixed effects regression model using maximum likelihood (ML). Prior to callingmixeff_hier_ml
the initialization functionmixeff_hier_init()
must be called.Deprecated since version 27.0.0.0:
mixeff_hier_ml
is deprecated. Please uselmm_fit()
instead. See also the Replacement Calls document.For full information please refer to the NAG Library document for g02je
https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/g02/g02jef.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.
- nvprint
, the number of variance components being estimated (excluding the overall variance, ).
- 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_ml
fits the specified model using a modified Newton optimization algorithm as implemented inopt.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 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_ml
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_ml
uses an iterative process to estimate . Due to the iterative nature of the estimation a set of initial values, , for is required.mixeff_hier_ml
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_ml
fits the model by maximizing the 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