G02JAF (PDF version)
G02 Chapter Contents
G02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G02JAF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

G02JAF fits a linear mixed effects regression model using restricted maximum likelihood (REML).

2  Specification

SUBROUTINE G02JAF ( N, NCOL, LDDAT, DAT, LEVELS, YVID, CWID, NFV, FVID, FINT, NRV, RVID, NVPR, VPR, RINT, SVID, GAMMA, NFF, NRF, DF, REML, LB, B, SE, MAXIT, TOL, WARN, IFAIL)
INTEGER  N, NCOL, LDDAT, LEVELS(NCOL), YVID, CWID, NFV, FVID(NFV), FINT, NRV, RVID(NRV), NVPR, VPR(NRV), RINT, SVID, NFF, NRF, DF, LB, MAXIT, WARN, IFAIL
REAL (KIND=nag_wp)  DAT(LDDAT,NCOL), GAMMA(NVPR+2), REML, B(LB), SE(LB), TOL

3  Description

G02JAF fits a model of the form:
y=Xβ+Zν+ε  
where and
Both ν  and ε  are assumed to have a Gaussian distribution with expectation zero and
Var ν ε = G 0 0 R  
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 expectations 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 γ , G02JAF 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. G02JAF 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).
G02JAF fits the model using a quasi-Newton algorithm to maximize the restricted log-likelihood function:
-2 l R = log V + n-p log r V-1 r + log X V-1 X + n-p 1+ log 2 π / n-p  
where
V = ZG Z + R,   r=y-Xb   and   b = X V-1 X -1 X V-1 y .  
Once the final estimates for γ *  have been obtained, the value of σR2  is given by:
σR2 = r V-1 r / n - p .  
Case weights, Wc , can be incorporated into the model by replacing XX  and ZZ  with XWcX  and ZWcZ  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  Arguments

1:     N – INTEGERInput
On entry: n, the number of observations.
Constraint: N1.
2:     NCOL – INTEGERInput
On entry: the number of columns in the data matrix, DAT.
Constraint: NCOL1.
3:     LDDAT – INTEGERInput
On entry: the first dimension of the array DAT as declared in the (sub)program from which G02JAF is called.
Constraint: LDDATN.
4:     DATLDDATNCOL – REAL (KIND=nag_wp) arrayInput
On entry: array containing all of the data. For the ith observation:
  • DATiYVID holds the dependent variable, y;
  • if CWID0, DATiCWID holds the case weights;
  • if SVID0, DATiSVID holds the subject variable.
The remaining columns hold the values of the independent variables.
Constraints:
  • if CWID0, DATiCWID0.0;
  • if LEVELSj1, 1DATijLEVELSj.
5:     LEVELSNCOL – INTEGER arrayInput
On entry: LEVELSi contains the number of levels associated with the ith variable of the data matrix DAT. If this variable is continuous or binary (i.e., only takes the values zero or one) then LEVELSi should be 1; if the variable is discrete then LEVELSi is the number of levels associated with it and DATji is assumed to take the values 1 to LEVELSi, for j=1,2,,N.
Constraint: LEVELSi1, for i=1,2,,NCOL.
6:     YVID – INTEGERInput
On entry: the column of DAT holding the dependent, y, variable.
Constraint: 1YVIDNCOL.
7:     CWID – INTEGERInput
On entry: the column of DAT holding the case weights.
If CWID=0, no weights are used.
Constraint: 0CWIDNCOL.
8:     NFV – INTEGERInput
On entry: the number of independent variables in the model which are to be treated as being fixed.
Constraint: 0NFV<NCOL.
9:     FVIDNFV – INTEGER arrayInput
On entry: the columns of the data matrix DAT holding the fixed independent variables with FVIDi  holding the column number corresponding to the i th fixed variable.
Constraint: 1FVIDiNCOL, for i=1,2,,NFV.
10:   FINT – INTEGERInput
On entry: flag indicating whether a fixed intercept is included (FINT=1).
Constraint: FINT=0 or 1.
11:   NRV – INTEGERInput
On entry: the number of independent variables in the model which are to be treated as being random.
Constraints:
  • 0NRV<NCOL;
  • NRV+RINT>0.
12:   RVIDNRV – INTEGER arrayInput
On entry: the columns of the data matrix DAT holding the random independent variables with RVIDi  holding the column number corresponding to the i th random variable.
Constraint: 1RVIDiNCOL, for i=1,2,,NRV.
13:   NVPR – INTEGERInput
On entry: if RINT=1 and SVID0, NVPR is the number of variance components being estimated-2, (g-1), else NVPR=g.
If NRV=0, NVPR is not referenced.
Constraint: if NRV0, 1NVPRNRV.
14:   VPRNRV – INTEGER arrayInput
On entry: VPRi  holds a flag indicating the variance of the i th random variable. The variance of the i th random variable is σ j 2 , where j = VPRi + 1  if RINT=1 and SVID0 and j = VPRi  otherwise. Random variables with the same value of j are assumed to be taken from the same distribution.
Constraint: 1VPRiNVPR, for i=1,2,,NRV.
15:   RINT – INTEGERInput
On entry: flag indicating whether a random intercept is included (RINT=1).
If SVID=0, RINT is not referenced.
Constraint: RINT=0 or 1.
16:   SVID – INTEGERInput
On entry: the column of DAT holding the subject variable.
If SVID=0, no subject variable is used.
Specifying a subject variable is equivalent to specifying the interaction between that variable and all of the random-effects. Letting the notation Z1 × ZS  denote the interaction between variables Z1  and ZS , fitting a model with RINT = 0 , random-effects Z1 + Z2  and subject variable ZS  is equivalent to fitting a model with random-effects Z1 × ZS + Z2 × ZS  and no subject variable. If RINT = 1  the model is equivalent to fitting ZS + Z1 × ZS + Z2 × ZS  and no subject variable.
Constraint: 0SVIDNCOL.
17:   GAMMANVPR+2 – 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,,g. If RINT=1 and SVID0, g=NVPR+1, else g=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,,g, holds the final estimate of σi2 and GAMMAg+1 holds the final estimate for σR2.
Constraint: GAMMA1=-1.0 ​ or ​ GAMMAi0.0, for i=1,2,,g.
18:   NFF – INTEGEROutput
On exit: the number of fixed effects estimated (i.e., the number of columns, p, in the design matrix X).
19:   NRF – INTEGEROutput
On exit: the number of random effects estimated (i.e., the number of columns, q, in the design matrix Z).
20:   DF – INTEGEROutput
On exit: the degrees of freedom.
21:   REML – REAL (KIND=nag_wp)Output
On exit: - 2 lR γ^  where lR  is the log of the restricted maximum likelihood calculated at γ^ , the estimated variance components returned in GAMMA.
22:   LB – INTEGERInput
On entry: the size of the array B.
Constraint: LB FINT + i=1 NFV maxLEVELSFVIDi-1,1 + LS × RINT + i=1 NRV LEVELSRVIDi  where LS = LEVELSSVID  if SVID0 and 1 otherwise.
23:   BLB – REAL (KIND=nag_wp) arrayOutput
On exit: the parameter estimates, β,ν, with the first NFF elements of B containing the fixed effect parameter estimates, β and the next NRF elements of B containing the random effect parameter estimates, ν.
Fixed effects
If FINT=1, B1 contains the estimate of the fixed intercept. Let Li  denote the number of levels associated with the ith fixed variable, that is Li = LEVELS FVIDi . Define
  • if FINT=1, F1 = 2  else if FINT=0, F1=1 ;
  • F i+1 = Fi + maxLi-1,1 , i1 .
Then for i=1,2,,NFV:
  • if Li > 1 , B Fi+j-2  contains the parameter estimate for the jth level of the ith fixed variable, for j=2,3,,Li;
  • if Li 1 , BFi  contains the parameter estimate for the ith fixed variable.
Random effects
Redefining Li  to denote the number of levels associated with the ith random variable, that is Li = LEVELS RVIDi . Define
  • if RINT=1, R1 = 2  else if RINT=0, R1=1 ;
    R i+1 = Ri + Li , i1 .
Then for i = 1 , 2 , , NRV :
  • if SVID=0,
    • if Li > 1 , B NFF + Ri +j-1  contains the parameter estimate for the jth level of the ith random variable, for j=1,2,,Li;
    • if Li 1 , B NFF + Ri  contains the parameter estimate for the ith random variable;
  • if SVID 0 ,
    • let LS  denote the number of levels associated with the subject variable, that is LS = LEVELS SVID ;
    • if Li > 1 , B NFF + s-1 LS + Ri + j - 1  contains the parameter estimate for the interaction between the sth level of the subject variable and the jth level of the ith random variable, for s=1,2,,LS and j=1,2,,Li;
    • if Li 1 , B NFF + s-1 LS + Ri  contains the parameter estimate for the interaction between the sth level of the subject variable and the ith random variable, for s=1,2,,LS;
    • if RINT=1, BNFF+1  contains the estimate of the random intercept.
24:   SELB – REAL (KIND=nag_wp) arrayOutput
On exit: the standard errors of the parameter estimates given in B.
25:   MAXIT – INTEGERInput
On entry: the maximum number of iterations.
If MAXIT < 0 , the default value of 100  is used.
If MAXIT=0, the parameter estimates β,ν  and corresponding standard errors are calculated based on the value of γ0  supplied in GAMMA.
26:   TOL – REAL (KIND=nag_wp)Input
On entry: the tolerance used to assess convergence.
If TOL0.0, the default value of ε0.7 is used, where ε is the machine precision.
27:   WARN – INTEGEROutput
On exit: is set to 1  if a variance component was estimated to be a negative value during the fitting process. Otherwise WARN is set to 0 .
If WARN=1, the negative estimate is set to zero and the estimation process allowed to continue.
28:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation 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 argument, 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, CWID=value and NCOL=value.
Constraint: 0CWIDNCOL  and any supplied weights must be 0.0.
On entry, FINT=value.
Constraint: FINT=0 or 1.
On entry, LB too small: LB=value.
On entry, LDDAT=value and N=value.
Constraint: LDDATN.
On entry, N=value.
Constraint: N1.
On entry, N<1 (nonzero weighted observations): N=value.
On entry, NCOL=value.
Constraint: NCOL1.
On entry, NFV=value and NCOL=value.
Constraint: 0NFV<NCOL.
On entry, NRV=value and NCOL=value.
Constraint: 0NRV<NCOL and NRV+RINT>0.
On entry, NVPR=value and NRV=value.
Constraint: 0NVPRNRV and (NRV0 or NVPR1).
On entry, RINT=value.
Constraint: RINT=0 or 1.
On entry, SVID=value and NCOL=value.
Constraint: 0SVIDNCOL.
On entry, YVID=value and NCOL=value.
Constraint: 1YVIDNCOL.
IFAIL=2
On entry, GAMMAi<0.0, for at least one i.
On entry, invalid data: categorical variable with value greater than that specified in LEVELS.
On entry, LEVELSI<1, for at least one I.
On entry, NCOL=value.
Constraint: 1FVIDiNCOL, for all i.
On entry, NCOL=value.
Constraint: 1RVIDiNCOL, for all i.
On entry, NVPR=value.
Constraint: 1VPRiNVPR, for all i.
IFAIL=3
Degrees of freedom <1: DF=value.
This is due to the number of parameters exceeding the effective number of observations.
IFAIL=4
Routine failed to converge in MAXIT iterations: MAXIT=value.
See Section 10 for advice.
Routine failed to converge to specified tolerance: TOL=value.
See Section 10 for advice.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7  Accuracy

The accuracy of the results can be adjusted through the use of the TOL argument.

8  Parallelism and Performance

G02JAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G02JAF 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 routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9  Further Comments

Wherever possible any block structure present in the design matrix Z should be modelled through a subject variable, specified via SVID, rather than being explicitly entered into DAT.
G02JAF uses an iterative process to fit the specified model and for some problems this process may fail to converge (see IFAIL=4). If the routine fails to converge then the maximum number of iterations (see MAXIT) or tolerance (see TOL) may require increasing; try a different starting estimate in GAMMA. Alternatively, the model can be fit using maximum likelihood (see G02JBF) or using the noniterative MIVQUE0.
To fit the model just using MIVQUE0, the first element of GAMMA should be set to -1.0 and MAXIT should be set to zero.
Although the quasi-Newton algorithm used in G02JAF tends to require more iterations before converging compared to the Newton–Raphson algorithm recommended by Wolfinger et al. (1994), it does not require the second derivatives of the likelihood function to be calculated and consequentially takes significantly less time per iteration.

10  Example

The following dataset is taken from Stroup (1989) and arises from a balanced split-plot design with the whole plots arranged in a randomized complete block-design.
In this example the full design matrix for the random independent variable, Z , is given by:
Z = 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1  
= A 0 0 0 0 A 0 0 0 0 A 0 0 0 0 A A 0 0 0 0 A 0 0 0 0 A 0 0 0 0 A , (1)
where
A = 1 1 0 0 1 0 1 0 1 0 0 1 .  
The block structure evident in (1) is modelled by specifying a four-level subject variable, taking the values 1 , 1 , 1 , 2 , 2 , 2 , 3 , 3 , 3 , 4 , 4 , 4 , 1 , 1 , 1 , 2 , 2 , 2 , 3 , 3 , 3 , 4 , 4 , 4 . The first column of 1s  is added to A  by setting RINT=1. The remaining columns of A are specified by a three level factor, taking the values, 1 , 2 , 3 , 1 , 2 , 3 , 1 , .

10.1  Program Text

Program Text (g02jafe.f90)

10.2  Program Data

Program Data (g02jafe.d)

10.3  Program Results

Program Results (g02jafe.r)


G02JAF (PDF version)
G02 Chapter Contents
G02 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2016