NAG Library Function Document
nag_ml_hier_mixed_regsn (g02jec)
1 Purpose
nag_ml_hier_mixed_regsn (g02jec) fits a multi-level linear mixed effects regression model using maximum likelihood (ML). Prior to calling nag_ml_hier_mixed_regsn (g02jec) the initialization function
nag_hier_mixed_init (g02jcc) must be called.
2 Specification
#include <nag.h> |
#include <nagg02.h> |
void |
nag_ml_hier_mixed_regsn (Integer lvpr,
const Integer vpr[],
Integer nvpr,
double gamma[],
Integer *effn,
Integer *rnkx,
Integer *ncov,
double *lnlike,
Integer lb,
Integer id[],
Integer pdid,
double b[],
double se[],
double czz[],
Integer pdczz,
double cxx[],
Integer pdcxx,
double cxz[],
Integer pdcxz,
const double rcomm[],
const Integer icomm[],
const Integer iopt[],
Integer liopt,
const double ropt[],
Integer lropt,
NagError *fail) |
|
3 Description
nag_ml_hier_mixed_regsn (g02jec) fits a model of the form:
where |
is a vector of observations on the dependent variable, |
|
is a known by design matrix for the fixed independent variables, |
|
is a vector of length of unknown fixed effects, |
|
is a known by 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
, nag_ml_hier_mixed_regsn (g02jec) uses an iterative process to estimate
. Due to the iterative nature of the estimation a set of initial values,
, for
is required. nag_ml_hier_mixed_regsn (g02jec) 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).
nag_ml_hier_mixed_regsn (g02jec) 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).
4 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
5 Arguments
Note: prior to calling nag_ml_hier_mixed_regsn (g02jec) the initialization function
nag_hier_mixed_init (g02jcc) must be called, therefore this documention should be read in conjunction with the document for
nag_hier_mixed_init (g02jcc).
In particular some argument names and conventions described in that document are also relevant here, but their definition has not been repeated. Specifically,
RNDM,
wt,
n,
nff,
nrf,
nlsv,
levels,
fixed,
DAT,
licomm and
lrcomm should be interpreted identically in both functions.
- 1:
– IntegerInput
-
On entry: the sum of the number of random parameters and the random intercept flags specified in the call to
nag_hier_mixed_init (g02jcc).
Constraint:
.
- 2:
– const IntegerInput
-
On entry: a vector of flags indicating the mapping between the random variables specified in
rndm and the variance components,
. See
Section 9 for more details.
Constraint:
, for .
- 3:
– IntegerInput
-
On entry: , the number of variance components being estimated (excluding the overall variance, ).
Constraint:
.
- 4:
– doubleInput/Output
-
On entry: holds the initial values of the variance components,
, with
the initial value for
, for
.
If
, the remaining elements of
gamma are ignored and the initial values for the variance components are estimated from the data using MIVQUE0.
On exit: , for , holds the final estimate of and holds the final estimate for .
Constraint:
, for .
- 5:
– Integer *Output
-
On exit: effective number of observations. If there are no weights (i.e., ), or all weights are nonzero, then .
- 6:
– Integer *Output
-
On exit: the rank of the design matrix, , for the fixed effects.
- 7:
– Integer *Output
-
On exit: number of variance components not estimated to be zero. If none of the variance components are estimated to be zero, then .
- 8:
– double *Output
-
On exit:
where
is the log of the maximum likelihood calculated at
, the estimated variance components returned in
gamma.
- 9:
– IntegerInput
-
On entry: the dimension of the arrays
b and
se.
Constraint:
.
- 10:
– IntegerOutput
-
Note: where appears in this document, it refers to the array element
.
On exit: an array describing the parameter estimates returned in
b. The first
columns of
ID describe the parameter estimates for the random effects and the last
nff columns the parameter estimates for the fixed effects.
The example program for this function includes a demonstration of decoding the parameter estimates given in
b using information from
id.
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 DAT when then
- if the th variable is continuous or binary, that is , then ;
- any remaining rows of the th column of ID 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 DAT 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 DAT 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 ID are set to .
In some situations, certain combinations of variables are never observed. In such circumstances all elements of the
th row of
ID are set to
.
- 11:
– IntegerInput
-
On entry: the stride separating matrix row elements in the array
id.
Constraint:
, i.e.,
maximum number of subject variables (see
nag_hier_mixed_init (g02jcc)).
- 12:
– doubleOutput
-
On exit: the parameter estimates, with the first
elements of
containing the parameter estimates for the random effects,
, and the remaining
nff elements containing the parameter estimates for the fixed effects,
. The order of these estimates are described by the
id argument.
- 13:
– doubleOutput
-
On exit: the standard errors of the parameter estimates given in
b.
- 14:
– doubleOutput
-
Note: the dimension,
dim, of the array
czz
must be at least
.
Where appears in this document, it refers to the array element
.
On exit: if
, then
CZZ holds the lower triangular portion of the matrix
, where
and
are the estimates of
and
respectively. If
then
CZZ holds this matrix in compressed form, with the first
nrf columns holding the part of the matrix corresponding to the first level of the overall subject variable, the next
nrf columns the part corresponding to the second level of the overall subject variable etc.
- 15:
– IntegerInput
-
On entry: the stride separating matrix row elements in the array
czz.
Constraint:
.
- 16:
– doubleOutput
-
Note: the dimension,
dim, of the array
cxx
must be at least
.
Where appears in this document, it refers to the array element
.
On exit:
CXX holds the lower triangular portion of the matrix
, where
is the estimated value of
.
- 17:
– IntegerInput
-
On entry: the stride separating matrix row elements in the array
cxx.
Constraint:
.
- 18:
– doubleOutput
-
Note: the dimension,
dim, of the array
cxz
must be at least
.
Where appears in this document, it refers to the array element
.
On exit: if
, then
CXZ holds the matrix
, where
and
are the estimates of
and
respectively. If
then
CXZ holds this matrix in compressed form, with the first
nrf columns holding the part of the matrix corresponding to the first level of the overall subject variable, the next
nrf columns the part corresponding to the second level of the overall subject variable etc.
- 19:
– IntegerInput
-
On entry: the stride separating matrix row elements in the array
cxz.
Constraint:
.
- 20:
– const doubleCommunication Array
-
Note: the dimension,
dim, of the array
rcomm
must be at least
.
On entry: communication array initialized by a call to
nag_hier_mixed_init (g02jcc).
- 21:
– const IntegerCommunication Array
-
Note: the dimension,
dim, of the array
icomm
must be at least
.
On entry: communication array initialized by a call to
nag_hier_mixed_init (g02jcc).
- 22:
– const IntegerInput
-
On entry: optional parameters passed to the optimization function.
By default nag_ml_hier_mixed_regsn (g02jec) fits the specified model using a modified Newton optimization algorithm as implemented in
the NAG Fortran Library routine
E04LBF.
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
the NAG Fortran Library routine
E04UCF
can be chosen by setting
. If
or
then
E04LBF
will be used.
Different optional parameters 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
liopt values of
iopt are used, so for example, if only the first element of
iopt needs changing and default values for all other optional parameters are sufficient
liopt can be set to
.
NAG Fortran Library routine
E04LBF
is being used.
|
Description | Equivalent
E04LBF
argument |
Default Value |
| Number of iterations |
MAXCAL
| |
| Unit number for monitoring information. See nag_open_file (x04acc) for details on how to assign a file to a unit number. | n/a | Output sent to stdout |
| Print optional parameters ( print) | n/a | (no printing performed) |
| Frequency that monitoring information is printed |
IPRINT
| |
| Optimizer used | n/a | n/a |
If requested, monitoring information is displayed in a similar format to that given by
E04LBF.
NAG Fortran Library routine
E04UCF
is being used.
|
Description | Equivalent
E04UCF
argument |
Default Value |
| Number of iterations |
Major Iteration Limit
| |
| Unit number for monitoring information. See nag_open_file (x04acc) for details on how to assign a file to a unit number. | n/a | Output sent to stdout |
| Print optional parameters ( 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
then default values are used for all optional parameters and
iopt may be set to
NULL.
- 23:
– IntegerInput
-
On entry: length of the options array
iopt.
- 24:
– const doubleInput
-
On entry: optional parameters passed to the optimization function.
Different optional parameters 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
lropt values of
ropt are used, so for example, if only the first element of
ropt needs changing and default values for all other optional parameters are sufficient
lropt can be set to
.
NAG Fortran Library routine
E04LBF
is being used.
|
Description | Equivalent
E04LBF
argument |
Default Value |
| Sweep tolerance | n/a | |
| Lower bound for | n/a | |
| Upper bound for | n/a | |
| Accuracy of linear minimizations |
ETA
| |
| Accuracy to which solution is required |
XTOL
| |
| Initial distance from solution |
STEPMX
| |
NAG Fortran Library routine
E04UCF
is being used.
|
Description | Equivalent
E04UCF
argument |
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
nag_machine_precision (X02AJC) and
denotes the
diagonal element of
.
If
then default values are used for all optional parameters and
ropt and may be set to
NULL.
- 25:
– IntegerInput
-
On entry: length of the options array
ropt.
- 26:
– NagError *Input/Output
-
The NAG error argument (see
Section 2.7 in How to Use the NAG Library and its Documentation).
6 Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
- NE_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_INT
-
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_ARRAY
-
On entry, at least one value of
i, for
, does not appear in
vpr.
On entry,
icomm has not been initialized correctly.
On entry, and .
Constraint: .
- NE_INTERNAL_ERROR
-
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact
NAG for assistance.
An unexpected error has been triggered by this function. Please contact
NAG.
See
Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
- NE_NEG_ELEMENT
-
At least one negative estimate for
gamma was obtained. All negative estimates have been set to zero.
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
- NE_REAL_ARRAY
-
On entry, .
Constraint: or .
- NW_KT_CONDITIONS
-
Current point cannot be improved upon.
- NW_NOT_CONVERGED
-
Optimal solution found, but requested accuracy not achieved.
- NW_TOO_MANY_ITER
-
Too many major iterations.
7 Accuracy
Not applicable.
8 Parallelism and Performance
nag_ml_hier_mixed_regsn (g02jec) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_ml_hier_mixed_regsn (g02jec) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
x06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
The argument
vpr gives the mapping between the random variables and the variance components. In most cases
, for
. However, in some cases it might be necessary to associate more than one random variable with a single variance component, for example, when the columns of
DAT hold dummy variables.
Consider a dataset with three variables:
where the first column corresponds to a categorical variable with three levels, the next to a categorical variable with two levels and the last column to a continuous variable. So in a call to
nag_hier_mixed_init (g02jcc)
also assume a model with no fixed effects, no random intercept, no nesting and all three variables being included as random effects, then
Each of the three columns in
DAT therefore correspond to a single variable and hence there are three variance components, one for each random variable included in the model, so
This is the recommended way of supplying the data to nag_ml_hier_mixed_regsn (g02jec), however it is possible to reformat the above dataset by replacing each of the categorical variables with a series of dummy variables, one for each level. The dataset then becomes
where each column only has one level
Again a model with no fixed effects, no random intercept, no nesting and all variables being included as random effects is required, so
With the data entered in this manner, the first three columns of
DAT correspond to a single variable (the first column of the original dataset) as do the next two columns (the second column of the original dataset). Therefore
vpr must reflect this
In most situations it is more efficient to supply the data to
nag_hier_mixed_init (g02jcc) in terms of categorical variables rather than transform them into dummy variables.
10 Example
This example fits a random effects model with three levels of nesting to a simulated dataset with observations and variables.
10.1 Program Text
Program Text (g02jece.c)
10.2 Program Data
Program Data (g02jece.d)
10.3 Program Results
Program Results (g02jece.r)