NAG Library Routine Document
G02JEF
1 Purpose
G02JEF fits a multi-level linear mixed effects regression model using maximum likelihood (ML). Prior to calling G02JEF the initialization routine
G02JCF must be called.
2 Specification
SUBROUTINE G02JEF ( |
LVPR, VPR, NVPR, GAMMA, EFFN, RNKX, NCOV, LNLIKE, LB, ID, LDID, B, SE, CZZ, LDCZZ, CXX, LDCXX, CXZ, LDCXZ, RCOMM, ICOMM, IOPT, LIOPT, ROPT, LROPT, IFAIL) |
INTEGER |
LVPR, VPR(LVPR), NVPR, EFFN, RNKX, NCOV, LB, ID(LDID,LB), LDID, LDCZZ, LDCXX, LDCXZ, ICOMM(*), IOPT(LIOPT), LIOPT, LROPT, IFAIL |
REAL (KIND=nag_wp) |
GAMMA(NVPR+1), LNLIKE, B(LB), SE(LB), CZZ(LDCZZ,*), CXX(LDCXX,*), CXZ(LDCXZ,*), RCOMM(*), ROPT(LROPT) |
|
3 Description
G02JEF fits a model of the form:
where |
y is a vector of n observations on the dependent variable, |
|
X is a known n by p design matrix for the fixed independent variables, |
|
β is a vector of length p of unknown fixed effects, |
|
Z is a known n by q design matrix for the random independent variables, |
|
ν is a vector of length q of unknown random effects, |
and |
ε is a vector of length n of unknown random errors. |
Both
ν
and
ε
are assumed to have a Gaussian distribution with expectation zero and variance/covariance matrix defined by
where
R=
σ
R
2
I
,
I
is the
n×n
identity matrix and
G
is a diagonal matrix. It is assumed that the random variables,
Z
, can be subdivided into
g
≤
q
groups with each group being identically distributed with expectation zero and variance
σi2
. The diagonal elements of matrix
G
therefore take one of the values
σi2
:
i=1,2,…,g
, 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
g+1
variance components
γ
, where
γ
=
σ12,σ22,…,
σ
g-1
2
,σg2,σR2
. Rather than working directly with
γ
, G02JEF uses an iterative process to estimate
γ*
=
σ12
/
σR2
,
σ22
/
σR2
,…,
σg-12
/
σR2
,
σg2
/
σR2
,1
. Due to the iterative nature of the estimation a set of initial values,
γ0
, for
γ*
is required. G02JEF 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).
G02JEF fits the model by maximizing the log-likelihood function:
where
Once the final estimates for
γ
*
have been obtained, the value of
σR2
is given by
Case weights,
Wc
, can be incorporated into the model by replacing
XTX
and
ZTZ
with
XTWcX
and
ZTWcZ
respectively, for a diagonal weight matrix
Wc
.
The log-likelihood,
lR, 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 Parameters
Note: prior to calling G02JEF the initialization routine
G02JCF must be called, therefore this documention should be read in conjunction with the document for
G02JCF.
In particular some parameter names and conventions described in that document are also relevant here, but their definition has not been repeated. Specifically,
RNDM,
WEIGHT,
N,
NFF,
NRF,
NLSV,
LEVELS,
FIXED,
DAT,
LICOMM and
LRCOMM should be interpreted identically in both routines.
- 1: LVPR – INTEGERInput
On entry: the sum of the number of random parameters and the random intercept flags specified in the call to
G02JCF.
Constraint:
LVPR=∑iRNDM1,i+RNDM2,i.
- 2: VPR(LVPR) – INTEGER arrayInput
On entry: a vector of flags indicating the mapping between the random variables specified in
RNDM and the variance components,
σi2. See
Section 8 for more details.
Constraint:
1≤VPRi≤NVPR, for i=1,2,…,LVPR.
- 3: NVPR – INTEGERInput
On entry: g, the number of variance components being estimated (excluding the overall variance, σR2).
Constraint:
1≤NVPR≤LVPR .
- 4: GAMMA(NVPR+1) – REAL (KIND=nag_wp) arrayInput/Output
On entry: holds the initial values of the variance components,
γ0 , with
GAMMAi the initial value for
σi2/σR2, for
i=1,2,…,NVPR.
If
GAMMA1=-1.0, the remaining elements of
GAMMA are ignored and the initial values for the variance components are estimated from the data using MIVQUE0.
On exit: GAMMAi, for i=1,2,…,NVPR, holds the final estimate of σi2 and GAMMANVPR+1 holds the final estimate for σR2.
Constraint:
GAMMA1=-1.0 or GAMMAi≥0.0, for i=1,2,…,g.
- 5: EFFN – INTEGEROutput
On exit: effective number of observations. If there are no weights (i.e., WEIGHT='U'), or all weights are nonzero, then EFFN=N.
- 6: RNKX – INTEGEROutput
On exit: the rank of the design matrix, X, for the fixed effects.
- 7: NCOV – INTEGEROutput
On exit: number of variance components not estimated to be zero. If none of the variance components are estimated to be zero, then NCOV=NVPR.
- 8: LNLIKE – REAL (KIND=nag_wp)Output
On exit:
- 2 lR γ^ where
lR is the log of the maximum likelihood calculated at
γ^ , the estimated variance components returned in
GAMMA.
- 9: LB – INTEGERInput
On entry: the dimension of the arrays
B and
SE and the second dimension of the array
ID as declared in the (sub)program from which G02JEF is called.
Constraint:
LB≥NFF+NRF×NLSV.
- 10: ID(LDID,LB) – INTEGER arrayOutput
On exit: an array describing the parameter estimates returned in
B. The first
NLSV×NRF columns of
ID describe the parameter estimates for the random effects and the last
NFF columns the parameter estimates for the fixed effects.
A print routine for decoding the parameter estimates given in
B using information from
ID is supplied with the example program for this routine.
For fixed effects:
- for l=NRF×NLSV+1 ,…, NRF×NLSV+NFF
- if Bl contains the parameter estimate for the intercept then
- if Bl contains the parameter estimate for the ith level of the jth fixed variable, that is the vector of values held in the kth column of DAT when FIXEDj+2=k then
- if the jth variable is continuous or binary, that is LEVELSFIXEDj+2=1, then ID3l=0;
- any remaining rows of the lth column of ID are set to 0.
For random effects:
- let
- NRb denote the number of random variables in the bth random statement, that is NRb=RNDM1,b;
- Rjb denote the jth random variable from the bth random statement, that is the vector of values held in the kth column of DAT when RNDM2+j,b=k;
- NSb denote the number of subject variables in the bth random statement, that is NSb=RNDM3+NRb,b;
- Sjb denote the jth subject variable from the bth random statement, that is the vector of values held in the kth column of DAT when RNDM3+NRb+j,b=k;
- LSjb denote the number of levels for Sjb, that is LSjb=LEVELSRNDM3+NRb+j,b;
- then
- for l=1,2,… NRF×NLSV, if Bl contains the parameter estimate for the ith level of Rjb when
Skb=sk, for k=1,2,…,NSb and 1≤sk≤LSjb, i.e., sk is a valid value for the kth subject variable, then
- if the parameter being estimated is for the intercept then ID2l=ID3l=0;
- if the jth variable is continuous, or binary, that is LSjb=1, then ID3l=0;
- the remaining rows of the lth column of ID are set to 0.
In some situations, certain combinations of variables are never observed. In such circumstances all elements of the
lth row of
ID are set to
-999.
- 11: LDID – INTEGERInput
On entry: the first dimension of the array
ID as declared in the (sub)program from which G02JEF is called.
Constraint:
LDID≥3+maxj RNDM 3+ RNDM 1,j ,j , i.e.,
3+ maximum number of subject variables (see
G02JCF).
- 12: B(LB) – REAL (KIND=nag_wp) arrayOutput
On exit: the parameter estimates, with the first
NRF×NLSV elements of
B 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 parameter.
- 13: SE(LB) – REAL (KIND=nag_wp) arrayOutput
On exit: the standard errors of the parameter estimates given in
B.
- 14: CZZ(LDCZZ,*) – REAL (KIND=nag_wp) arrayOutput
-
Note: the second dimension of the array
CZZ
must be at least
NRF×NLSV (see
G02JCF).
On exit: if
NLSV=1, then
CZZ holds the lower triangular portion of the matrix
1/ σ 2 ZT R^-1 Z + G^-1 , where
R^ and
G^ are the estimates of
R and
G respectively. If
NLSV>1 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: LDCZZ – INTEGERInput
On entry: the first dimension of the array
CZZ as declared in the (sub)program from which G02JEF is called.
Constraint:
LDCZZ≥NRF.
- 16: CXX(LDCXX,*) – REAL (KIND=nag_wp) arrayOutput
-
Note: the second dimension of the array
CXX
must be at least
NFF (see
G02JCF).
On exit:
CXX holds the lower triangular portion of the matrix
1/ σ2 XT V^-1 X , where
V^ is the estimated value of
V.
- 17: LDCXX – INTEGERInput
On entry: the first dimension of the array
CXX as declared in the (sub)program from which G02JEF is called.
Constraint:
LDCXX≥NFF.
- 18: CXZ(LDCXZ,*) – REAL (KIND=nag_wp) arrayOutput
-
Note: the second dimension of the array
CXZ
must be at least
NLSV×NRF (see
G02JCF).
On exit: if
NLSV=1, then
CXZ holds the matrix
1/σ2 XT V^-1 Z G^ , where
V^ and
G^ are the estimates of
V and
G respectively. If
NLSV>1 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: LDCXZ – INTEGERInput
On entry: the first dimension of the array
CXZ as declared in the (sub)program from which G02JEF is called.
Constraint:
LDCXZ≥NFF.
- 20: RCOMM(*) – REAL (KIND=nag_wp) arrayCommunication Array
-
Note: the dimension of the array
RCOMM
must be at least
LRCOMM (see
G02JCF).
On entry: communication array initialized by a call to
G02JCF.
- 21: ICOMM(*) – INTEGER arrayCommunication Array
-
Note: the dimension of the array
ICOMM
must be at least
LICOMM (see
G02JCF).
On entry: communication array initialized by a call to
G02JCF.
- 22: IOPT(LIOPT) – INTEGER arrayInput
On entry: optional parameters passed to the optimization routine.
By default G02JEF fits the specified model using a modified Newton optimization algorithm as implemented in
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
E04UCA
can be chosen by setting
IOPT5=1. If
LIOPT<4 or
IOPT5≠1 then
E04LBF
will be used.
Different optional parameters are available depending on the optimization routine used. In all cases, using a value of
-1 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
1.
E04LBF
is being used
i |
Description | Equivalent
E04LBF parameter |
Default Value |
1 | Number of iterations |
MAXCAL
| 1000 |
2 | Unit number for monitoring information | n/a | As returned by X04ABF |
3 | Print optional parameters (1= print) | n/a | -1 (no printing performed) |
4 | Frequency that monitoring information is printed |
IPRINT
| -1 |
5 | Optimizer used | n/a | n/a |
If requested, monitoring information is displayed in a similar format to that given by
E04LBF.
E04UCA
is being used
i |
Description | Equivalent
E04UCA parameter |
Default Value |
1 | Number of iterations |
Major Iteration Limit
| max50,3×NVPR |
2 | Unit number for monitoring information | n/a | As returned by X04ABF |
3 | Print optional parameters (1= print, otherwise no print) |
List/Nolist
| -1 (no printing performed) |
4 | Frequency that monitoring information is printed |
Major Print Level
| 0 |
5 | Optimizer used | n/a | n/a |
6 | Number of minor iterations |
Minor Iteration Limit
| max50,3×NVPR |
7 | Frequency that additional monitoring information is printed |
Minor Print Level
| 0 |
- 23: LIOPT – INTEGERInput
On entry: length of the options array
IOPT. If
LIOPT≤0 then
IOPT is not referenced and default values are used for all optional parameters.
- 24: ROPT(LROPT) – REAL (KIND=nag_wp) arrayInput
On entry: optional parameters passed to the optimization routine.
Different optional parameters are available depending on the optimization routine used. In all cases, using a value of
-1.0 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
1.
E04LBF
is being used
i |
Description | Equivalent
E04LBF parameter |
Default Value |
1 | Sweep tolerance | n/a | maxeps,eps×maxizzii |
2 | Accuracy of linear minimizations |
ETA
| 0.9 |
3 | Accuracy to which solution is required |
XTOL
| 0.0 |
4 | Initial distance from solution |
STEPMX
| 100000.0 |
E04UCA
is being used
i |
Description | Equivalent
E04UCA parameter |
Default Value |
1 | Sweep tolerance | n/a | maxeps,eps×maxizzii |
2 | Lower bound for γ* | n/a | eps/100 |
3 | Upper bound for γ* | n/a | 1020 |
4 | Line search tolerance |
Line Search Tolerance
| 0.9 |
5 | Optimality tolerance |
Optimality Tolerance
| eps0.72 |
where
eps is the
machine precision returned by
X02AJF and
zzii denotes the
i diagonal element of
ZTZ.
- 25: LROPT – INTEGERInput
On entry: length of the options array
ROPT. If
LROPT≤0 then
ROPT is not referenced and default values are used for all optional parameters.
- 26: IFAIL – INTEGERInput/Output
On entry:
IFAIL must be set to
0,
-1 or 1. If you are unfamiliar with this parameter you should refer to
Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
-1 or 1 is recommended. If the output of error messages is undesirable, then the value
1 is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is
0.
When the value -1 or 1 is used it is essential to test the value of IFAIL on exit.
On exit:
IFAIL=0 unless the routine detects an error or a warning has been flagged (see
Section 6).
6 Error Indicators and Warnings
If on entry
IFAIL=0 or
-1, explanatory error messages are output on the current error message unit (as defined by
X04AAF).
Errors or warnings detected by the routine:
- IFAIL=1
On entry,
LVPR is too small.
- IFAIL=2
On entry, VPRi<1 or >NVPR.
- IFAIL=3
On entry, | NVPR<1, |
or | NVPR>LVPR. |
- IFAIL=4
On entry, GAMMA1≠-1.0 and GAMMAi<0.
- IFAIL=9
On entry,
LB is too small.
- IFAIL=11
On entry,
LDID is too small.
- IFAIL=15
On entry,
LDCZZ is too small.
- IFAIL=17
On entry,
LDCXX is too small.
- IFAIL=19
On entry,
LDCXZ is too small.
- IFAIL=21
On entry,
ICOMM has not been initialized.
- IFAIL=101
Optimal solution found, but requested accuracy not achieved.
- IFAIL=102
Too many major iterations.
- IFAIL=103
Current point cannot be improved upon.
- IFAIL=104
At least one negative estimate for gamma was obtained. All negative estimates have been set to zero.
7 Accuracy
Not applicable.
8 Further Comments
The parameter
VPR gives the mapping between the random variables and the variance components. In most cases
VPRi=i, for
i=1,2,…,∑iRNDM1,i+RNDM2,i. 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
G02JCF
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 G02JEF, 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
G02JCF in terms of categorical variables rather than transform them into dummy variables.
9 Example
This example fits a random effects model with three levels of nesting to a simulated dataset with 90 observations and 12 variables.
9.1 Program Text
Program Text (g02jefe.f90)
9.2 Program Data
Program Data (g02jefe.d)
9.3 Program Results
Program Results (g02jefe.r)