NAG FL Interface
g02jcf (mixeff_​hier_​init)

Note: this routine is deprecated. Replaced by g02jff.
Settings help

FL Name Style:


FL Specification Language:


1 Purpose

g02jcf preprocesses a dataset prior to fitting a linear mixed effects regression model of the following form via either g02jdf or g02jef.

2 Specification

Fortran Interface
Subroutine g02jcf ( weight, n, ncol, dat, lddat, levels, y, wt, fixed, lfixed, nrndm, rndm, ldrndm, nff, nlsv, nrf, rcomm, lrcomm, icomm, licomm, ifail)
Integer, Intent (In) :: n, ncol, lddat, levels(ncol), fixed(lfixed), lfixed, nrndm, rndm(ldrndm,*), ldrndm, lrcomm, licomm
Integer, Intent (Inout) :: ifail
Integer, Intent (Out) :: nff, nlsv, nrf, icomm(licomm)
Real (Kind=nag_wp), Intent (In) :: dat(lddat,*), y(n), wt(*)
Real (Kind=nag_wp), Intent (Out) :: rcomm(lrcomm)
Character (1), Intent (In) :: weight
C Header Interface
#include <nag.h>
void  g02jcf_ (const char *weight, const Integer *n, const Integer *ncol, const double dat[], const Integer *lddat, const Integer levels[], const double y[], const double wt[], const Integer fixed[], const Integer *lfixed, const Integer *nrndm, const Integer rndm[], const Integer *ldrndm, Integer *nff, Integer *nlsv, Integer *nrf, double rcomm[], const Integer *lrcomm, Integer icomm[], const Integer *licomm, Integer *ifail, const Charlen length_weight)
The routine may be called by the names g02jcf or nagf_correg_mixeff_hier_init.

3 Description

g02jcf must be called prior to fitting a linear mixed effects regression model with either g02jdf or g02jef.
The model fitting routines g02jdf and g02jef fit a model of the following form:
y=Xβ+Zν+ε  
where y is a vector of n observations on the dependent variable,
X is an n×p design matrix of fixed independent variables,
β is a vector of p unknown fixed effects,
Z is an n×q design matrix of random independent variables,
ν is a vector of length q of unknown random effects,
ε is a vector of length n of unknown random errors,
and ν and ε are Normally distributed with expectation zero and variance/covariance matrix defined by
Var[ ν ε ] = [ G 0 0 R ]  
where R= σ R 2 I , I is the n×n identity matrix and G is a diagonal matrix.
Case weights can be incorporated into the model by replacing X and Z with Wc1/2X and Wc1/2Z respectively where Wc is a diagonal weight matrix.

4 References

None.

5 Arguments

1: weight Character(1) Input
On entry: indicates if weights are to be used.
weight='U'
No weights are used.
weight='W'
Case weights are used and must be supplied in array wt.
Constraint: weight='U' or 'W'.
2: n Integer Input
On entry: n, the number of observations.
The effective number of observations, that is the number of observations with nonzero weight (see wt for more detail), must be greater than the number of fixed effects in the model (as returned in nff).
Constraint: n1.
3: ncol Integer Input
On entry: the number of columns in the data matrix, dat.
Constraint: ncol0.
4: dat(lddat,*) Real (Kind=nag_wp) array Input
Note: the second dimension of the array dat must be at least ncol.
On entry: a matrix of data, with dat(i,j) holding the ith observation on the jth variable. The two design matrices X and Z are constructed from dat and the information given in fixed (for X) and rndm (for Z).
Constraint: if levels(j)1,1dat(i,j)levels(j).
5: lddat Integer Input
On entry: the first dimension of the array dat as declared in the (sub)program from which g02jcf is called.
Constraint: lddatn.
6: levels(ncol) Integer array Input
On entry: levels(i) contains the number of levels associated with the ith variable held in dat.
If the ith variable is continuous or binary (i.e., only takes the values zero or one), then levels(i) must be set to 1. Otherwise the ith variable is assumed to take an integer value between 1 and levels(i), (i.e., the ith variable is discrete with levels(i) levels).
Constraint: levels(i)1, for i=1,2,,ncol.
7: y(n) Real (Kind=nag_wp) array Input
On entry: y, the vector of observations on the dependent variable.
8: wt(*) Real (Kind=nag_wp) array Input
Note: the dimension of the array wt must be at least n if weight='W'.
On entry: if weight='W', wt must contain the diagonal elements of the weight matrix Wc.
If wt(i)=0.0, the ith observation is not included in the model and the effective number of observations is the number of observations with nonzero weights.
If weight='U', wt is not referenced and the effective number of observations is n.
Constraint: if weight='W', wt(i)0.0, for i=1,2,,n.
9: fixed(lfixed) Integer array Input
On entry: defines the structure of the fixed effects design matrix, X.
fixed(1)
The number of variables, NF, to include as fixed effects (not including the intercept if present).
fixed(2)
The fixed intercept flag which must contain 1 if a fixed intercept is to be included and 0 otherwise.
fixed(2+i)
The column of dat holding the ith fixed variable, for i=1,2,,fixed(1).
See Section 9.1 for more details on the construction of X.
Constraints:
  • fixed(1)0;
  • fixed(2)=0 or 1;
  • 1fixed(2+i)ncol, for i=1,2,,fixed(1).
10: lfixed Integer Input
On entry: length of the vector fixed.
Constraint: lfixed2+fixed(1).
11: nrndm Integer Input
On entry: the number of columns in rndm.
Constraint: nrndm>0.
12: rndm(ldrndm,*) Integer array Input
Note: the second dimension of the array rndm must be at least nrndm.
On entry: rndm(i,j) defines the structure of the random effects design matrix, Z. The bth column of rndm defines a block of columns in the design matrix Z.
rndm(1,b)
The number of variables, NRb, to include as random effects in the bth block (not including the random intercept if present).
rndm(2,b)
The random intercept flag which must contain 1 if block b includes a random intercept and 0 otherwise.
rndm(2+i,b)
The column of dat holding the ith random variable in the bth block, for i=1,2,,rndm(1,b).
rndm(3+NRb,b)
The number of subject variables, NSb, for the bth block. The subject variables define the nesting structure for this block.
rndm(3+NRb+i,b)
The column of dat holding the ith subject variable in the bth block, for i=1,2,,rndm(3+NRb,b).
See Section 9.2 for more details on the construction of Z.
Constraints:
  • rndm(1,b)0;
  • rndm(2,b)=0 or 1;
  • at least one random variable or random intercept must be specified in each block, i.e., rndm(1,b) + rndm(2,b) > 0 ;
  • the column identifiers associated with the random variables must be in the range 1 to ncol, i.e., 1 rndm(2+i,b) ncol , for i=1,2,,rndm(1,b);
  • rndm(3+NRb,b) 0 ;
  • the column identifiers associated with the subject variables must be in the range 1 to ncol, i.e., 1 rndm(3+ N R b +i ,b) ncol , for i=1,2,,rndm(3+NRb,b).
13: ldrndm Integer Input
On entry: the first dimension of the array rndm as declared in the (sub)program from which g02jcf is called.
Constraint: ldrndm max b (3+NRb+NSb) .
14: nff Integer Output
On exit: p, the number of fixed effects estimated, i.e., the number of columns in the design matrix X.
15: nlsv Integer Output
On exit: the number of levels for the overall subject variable (see Section 9.2 for a description of what this means). If there is no overall subject variable, nlsv=1.
16: nrf Integer Output
On exit: the number of random effects estimated in each of the overall subject blocks. The number of columns in the design matrix Z is given by q=nrf×nlsv.
17: rcomm(lrcomm) Real (Kind=nag_wp) array Communication Array
On exit: communication array as required by the analysis routines g02jdf and g02jef.
18: lrcomm Integer Input
On entry: the dimension of the array rcomm as declared in the (sub)program from which g02jcf is called.
Constraint: lrcomm(nff×nrf+nrf×nrf+nrf)×nlsv+nff×nff+nff+2.
19: icomm(licomm) Integer array Communication Array
On exit: if licomm=2, icomm(1) holds the minimum required value for licomm and icomm(2) holds the minimum required value for lrcomm, otherwise icomm is a communication array as required by the analysis routines g02jdf and g02jef.
20: licomm Integer Input
On entry: the dimension of the array icomm as declared in the (sub)program from which g02jcf is called.
Constraint: licomm=2 or licomm34+ NF×(MFL+1)+ nrndm×MNR×MRL+(LRNDM+2)×nrndm+ ncol+LDID×LB,
where
  • MNR = maxb ( N R b ) ,
  • MFL=maxi (levels(fixed(2+i))) ,
  • MRL=maxb,i (levels(rndm(2+i,b))) ,
  • LDID=maxb NSb ,
  • LB=nff+nrf×nlsv, and
  • LRNDM= max b (3+NRb+NSb)
21: ifail Integer Input/Output
On entry: ifail must be set to 0, −1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of −1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value −1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value 0 is recommended. 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, weight had an illegal value.
Constraint: weight='U' or 'W'.
ifail=2
On entry, n=value.
Constraint: n1.
ifail=3
On entry, ncol=value.
Constraint: ncol0.
ifail=4
On entry, variable j of observation i is less than 1 or greater than levels(j): i=value, j=value, value =value, levels(j)=value.
ifail=5
On entry, lddat=value and n=value.
Constraint: lddatn.
ifail=6
On entry, levels(value)=value.
Constraint: levels(i)1.
ifail=8
On entry, wt(value)=value.
Constraint: wt(i)0.0.
ifail=9
On entry, number of fixed parameters, value is less than zero.
ifail=10
On entry, lfixed=value.
Constraint: lfixedvalue.
ifail=11
On entry, nrndm=value.
Constraint: nrndm>0.
ifail=12
On entry, number of random parameters for random statement i is less than 0: i=value, number of parameters =value.
ifail=13
On entry, ldrndm=value.
Constraint: ldrndmvalue.
ifail=18
On entry, lrcomm=value.
Constraint: lrcommvalue.
ifail=20
On entry, licomm=value.
Constraint: licommvalue.
ifail=102
On entry, more fixed factors than observations, n=value.
Constraint: nvalue.
ifail=108
On entry, no observations due to zero weights.
ifail=109
On entry, invalid value for fixed intercept flag: value =value.
ifail=112
On entry, invalid value for random intercept flag for random statement i: i=value, value =value.
ifail=209
On entry, index of fixed variable j is less than 1 or greater than ncol: j=value, index =value and ncol=value.
ifail=212
On entry, must be at least one parameter, or an intercept in each random statement i: i=value.
ifail=312
On entry, index of random variable j in random statement i is less than 1 or greater than ncol: i=value, j=value, index =value and ncol=value.
ifail=412
On entry, number of subject parameters for random statement i is less than 0: i=value, number of parameters =value.
ifail=512
On entry, nesting variable j in random statement i has one level: j=value, i=value.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
g02jcf is not threaded in any implementation.

9 Further Comments

9.1 Construction of the fixed effects design matrix, X

Let
The design matrix for the fixed effects, X, is constructed as follows:
The number of columns in the design matrix, X, is, therefore, given by
p= 1+ j=1 N F (levels(fixed( 2+j ))-1) .  
This quantity is returned in nff.
In summary, g02jcf converts all non-binary categorical variables (i.e., where L(Fj)>1) to dummy variables. If a fixed intercept is included in the model then the first level of all such variables is dropped. If a fixed intercept is not included in the model then the first level of all such variables, other than the first, is dropped. The variables are added into the model in the order they are specified in fixed.

9.2 Construction of random effects design matrix, Z

Let
The design matrix for the random effects, Z, is constructed as follows:
In summary, each column of rndm defines a block of consecutive columns in Z. g02jcf converts all non-binary categorical variables (i.e., where L(Rjb) or L(Sjb)>1) to dummy variables. All random variables defined within a column of rndm are nested within all subject variables defined in the same column of rndm. In addition each of the subject variables are nested within each other, starting with the first (i.e., each of the Rjb,j=1,2,,NRb are nested within S1b which in turn is nested within S2b, which in turn is nested within S3b, etc.).
If the last subject variable in each column of rndm are the same (i.e., SNS11 = SNS22 = = SNSbb ) then all random effects in the model are nested within this variable. In such instances the last subject variable ( SNS11 ) is called the overall subject variable. The fact that all of the random effects in the model are nested within the overall subject variable means that ZTZ is block diagonal in structure. This fact can be utilised to improve the efficiency of the underlying computation and reduce the amount of internal storage required. The number of levels in the overall subject variable is returned in nlsv=L(SNS11).
If the last k subject variables in each column of rndm are the same, for k>1 then the overall subject variable is defined as the interaction of these k variables and
nlsv= j=NS1-k+1 NS1 L(Sj1) .  
If there is no overall subject variable then nlsv=1.
The number of columns in the design matrix Z is given by q=nrf×nlsv.

10 Example

See Section 10 in g02jdf and g02jef.