$Id: EXAMPLES,v 1.2 1998/03/24 22:44:19 bates Exp $

	    Linear mixed-effects models in S-PLUS and in R

Eventually this file will be extended to several examples of fitting
linear mixed-effects models in S-PLUS and in R.

1) Growth curve data.
The Pothoff and Roy orthodontic data in the object Orthodont gives the 
distance between the pterygomaxillary fissure and the pituitary
measured on 37 children, 16 males and 11 females.

The Orthodont object is a groupedData object that inherits from the
data.frame class and has a formula that describes the response, a
primary covariate, and a grouping factor for the observations (rows).

 R> library( lme )
 R> data( Orthodont )
 R> formula( Orthodont )
 distance ~ age | Subject

The data can be summarized by group.  Numerical factors are, by
default, summarized by mean.

 R> gsummary( Orthodont )
     distance age Subject    Sex
 M16   23.000  11     M16   Male
 M05   23.000  11     M05   Male
 M02   23.375  11     M02   Male
 M11   23.625  11     M11   Male
 M07   23.750  11     M07   Male
 M08   23.875  11     M08   Male
 M03   24.250  11     M03   Male
 M12   24.250  11     M12   Male
 M13   24.250  11     M13   Male
 M14   24.875  11     M14   Male
 M09   25.125  11     M09   Male
 M15   25.875  11     M15   Male
 M06   26.375  11     M06   Male
 M04   26.625  11     M04   Male
 M01   27.750  11     M01   Male
 M10   29.500  11     M10   Male
 F10   18.500  11     F10 Female
 F09   21.125  11     F09 Female
 F06   21.125  11     F06 Female
 F01   21.375  11     F01 Female
 F05   22.625  11     F05 Female
 F07   23.000  11     F07 Female
 F02   23.000  11     F02 Female
 F08   23.375  11     F08 Female
 F03   23.750  11     F03 Female
 F04   24.875  11     F04 Female
 F11   26.375  11     F11 Female

Fitting a linear mixed-effects model in the Laird-Ware formulation
requires a linear model expression for the fixed effects and a
one-sided linear models expression for the random effects.

 R> fm1 <- lme( distance ~ age, data = Orthodont )
 iteration = 0
 Step:
 [1] 0 0 0
 Parameter:
 [1] -0.78085  0.24386  4.08178
 Function Value
 [1] 319.22
 Gradient:
 [1]  0.116421 -0.212138  0.039396

 iteration = 1
 Step:
 [1] -0.0042306  0.0077089 -0.0014316
 Parameter:
 [1] -0.78508  0.25157  4.08034
 Function Value
 [1] 319.22
 Gradient:
 [1] 0.15801 0.10318 0.09106

 iteration = 2
 Step:
 [1] -0.0088645  0.0018959 -0.0043699
 Parameter:
 [1] -0.79394  0.25346  4.07597
 Function Value
 [1] 319.22
 Gradient:
 [1] 0.155473 0.101664 0.080357

 iteration = 3
 Step:
 [1] -0.216080  0.043828 -0.098615
 Parameter:
 [1] -1.01002  0.29729  3.97736
 Function Value
 [1] 319.2
 Gradient:
 [1]  0.07691  0.24137 -0.18092

 iteration = 4
 Step:
 [1]  0.041981 -0.013787  0.025174
 Parameter:
 [1] -0.96804  0.28351  4.00253
 Function Value
 [1] 319.2
 Gradient:
 [1]  0.057707 -0.058101 -0.122569

 iteration = 5
 Step:
 [1] -0.0103832  0.0014879  0.0018526
 Parameter:
 [1] -0.97842  0.28499  4.00439
 Function Value
 [1] 319.2
 Gradient:
 [1]  0.048030 -0.036508 -0.099279

 iteration = 6
 Step:
 [1] -0.0428616  0.0049405  0.0092540
 Parameter:
 [1] -1.02129  0.28993  4.01364
 Function Value
 [1] 319.20
 Gradient:
 [1] -0.00260126  0.00066353 -0.00046891

 iteration = 7
 Step:
 [1]  0.00328453 -0.00049220  0.00075056
 Parameter:
 [1] -1.01800  0.28944  4.01439
 Function Value
 [1] 319.20
 Gradient:
 [1]  2.8617e-04  1.3134e-03 -8.6092e-06

 iteration = 8
 Parameter:
 [1] -1.01810  0.28943  4.01440
 Function Value
 [1] 319.20
 Gradient:
 [1] -3.9083e-07 -4.5759e-05 -2.7187e-05

 Relative gradient close to zero.
 Current iterate is probably solution.

 R> summary( fm1 )
 Call:
   Fixed: distance ~ age
  Groups: list(~Subject) 
    Data: Orthodont 

 Estimation Method: ML 

 Random effects:
  Formula: ~age | Subject
  Structure: General positive-definite
          StdDev  Corr  
 X1       2.19410 X1    
 age      0.21492 -0.581
 Residual 1.31004       

 Fixed Effects Estimate(s):
               Value Std.Error z-value p-value
 (Intercept) 16.7611    0.7608 22.0322       0
 age          0.6602    0.0699  9.4418       0
  Correlation: 
     (Intr)
 age -0.848

 Standardized Within-Group Residuals:
        Min         Q1        Med         Q3        Max 
 -3.3059712 -0.4874307  0.0075982  0.4822374  3.9227925 

 Number of Observations: 108
 Number of Groups: 27 
 R> fm2 <- lme( distance ~ age * Sex, data = Orthodont,
 +            random = ~ age | Subject )
 iteration = 0
 Step:
 [1] 0 0 0
 Parameter:
 [1] -0.87840  0.22850  4.77119
 Function Value
 [1] 313.50
 Gradient:
 [1]  4.5703e-02 -9.5188e-02 -6.2786e-06

 iteration = 1
 Step:
 [1] -8.0164e-04  1.6696e-03  1.1013e-07
 Parameter:
 [1] -0.87921  0.23017  4.77119
 Function Value
 [1] 313.50
 Gradient:
 [1] 0.064788 0.030936 0.014645

 iteration = 2
 Step:
 [1] -0.00152742  0.00026330 -0.00025757
 Parameter:
 [1] -0.88073  0.23044  4.77093
 Function Value
 [1] 313.50
 Gradient:
 [1] 0.063229 0.030415 0.015469

 iteration = 3
 Step:
 [1] -0.070119  0.012060 -0.012772
 Parameter:
 [1] -0.95085  0.24250  4.75816
 Function Value
 [1] 313.49
 Gradient:
 [1] -0.0116085  0.0047212  0.0527394

 iteration = 4
 Step:
 [1]  0.00257761 -0.00046653 -0.00044041
 Parameter:
 [1] -0.94828  0.24203  4.75772
 Function Value
 [1] 313.49
 Gradient:
 [1] -0.009533 -0.004846  0.048605

 iteration = 5
 Step:
 [1]  0.00575375 -0.00056593 -0.00637671
 Parameter:
 [1] -0.94252  0.24147  4.75134
 Function Value
 [1] 313.49
 Gradient:
 [1] -0.0013527 -0.0344111  0.0288800

 iteration = 6
 Step:
 [1] -0.0026348  0.0015665 -0.0121840
 Parameter:
 [1] -0.94516  0.24303  4.73916
 Function Value
 [1] 313.49
 Gradient:
 [1]  0.0046930 -0.0459594  0.0077097

 iteration = 7
 Step:
 [1] -0.0118687  0.0034913 -0.0137159
 Parameter:
 [1] -0.95702  0.24652  4.72544
 Function Value
 [1] 313.49
 Gradient:
 [1]  0.0055157 -0.0279115 -0.0057564

 iteration = 8
 Step:
 [1] -0.0085823  0.0019951 -0.0040852
 Parameter:
 [1] -0.96561  0.24852  4.72135
 Function Value
 [1] 313.49
 Gradient:
 [1]  0.0019985 -0.0064654 -0.0036972

 iteration = 9
 Step:
 [1] -0.00198203  0.00033311  0.00040412
 Parameter:
 [1] -0.96759  0.24885  4.72176
 Function Value
 [1] 313.49
 Gradient:
 [1]  0.00013023 -0.00027444 -0.00044782

 iteration = 10
 Parameter:
 [1] -0.96757  0.24883  4.72197
 Function Value
 [1] 313.49
 Gradient:
 [1] -1.7053e-06  4.6043e-06 -1.2604e-05

 Relative gradient close to zero.
 Current iterate is probably solution.

 R> summary( fm2 )
 Call:
   Fixed: distance ~ age * Sex
  Groups: list(~Subject) 
    Data: Orthodont 

 Estimation Method: ML 

 Random effects:
  Formula: ~age | Subject
  Structure: General positive-definite
          StdDev  Corr  
 X1       2.13470 X1    
 age      0.15414 -0.603
 Residual 1.31004       

 Fixed Effects Estimate(s):
                 Value Std.Error z-value p-value
 (Intercept)   16.3406    0.9801 16.6727  0.0000
 age            0.7844    0.0828  9.4785  0.0000
 SexFemale      1.0321    1.5355  0.6722  0.5015
 age.SexFemale -0.3048    0.1296 -2.3512  0.0187
  Correlation: 
               (Intr) age    SexFml
 age           -0.880              
 SexFemale     -0.638  0.562       
 age.SexFemale  0.562 -0.638 -0.880

 Standardized Within-Group Residuals:
       Min        Q1       Med        Q3       Max 
 -3.336028 -0.415397  0.010391  0.491693  3.858195 

 Number of Observations: 108
 Number of Groups: 27 
 R> anova( fm1, fm2 )
 Error: names attribute must be the same length as the vector
 R> traceback()
 [1] "names(package:base)"
 R> fm3 <- lme( distance ~ age * Sex, data = Orthodont, random = ~ 1 )

 Process R segmentation fault at Tue Mar 24 10:40:08 1998

Some parts of this work but not as well as they should.  Compare with:
 
 S> find( Orthodont )
 [1] "../NLMEDATA/.Data"                 
 [2] "/s/splus-3.4r1/lib/splus/.Datasets"
 S> formula( Orthodont )
 distance ~ age | Subject
 S> fm1 <- lme( distance ~ age, data = Orthodont, random = ~ age,
 +              control = list(msVerbose = T) )
 Iteration:  0 ,  1  function calls, F=  319.22 
 Parameters:
 [1] -0.78085  0.24386  4.08178
 Iteration:  1 ,  2  function calls, F=  319.2 
 Parameters:
 [1] -1.10715  0.31031  3.98584
 Iteration:  2 ,  3  function calls, F=  319.2 
 Parameters:
 [1] -1.02838  0.29186  4.01068
 Iteration:  3 ,  4  function calls, F=  319.2 
 Parameters:
 [1] -1.01822  0.28946  4.01435
 S> fm2 <- lme( distance ~ age * Sex, data = Orthodont, 
 +              random = ~ age, control = list(msVerbose = T) )
 Iteration:  0 ,  1  function calls, F=  313.5 
 Parameters:
 [1] -0.8784  0.2285  4.7712
 Iteration:  1 ,  2  function calls, F=  313.49 
 Parameters:
 [1] -0.97759  0.25175  4.71388
 Iteration:  2 ,  3  function calls, F=  313.49 
 Parameters:
 [1] -0.96772  0.24888  4.72182
 S> anova( fm1, fm2 )
     Model df    AIC    BIC  logLik    Test Lik.Ratio   p-value 
 fm1     1  6 451.21 467.30 -219.61                            
 fm2     2  8 443.81 465.26 -213.90 1 vs. 2    11.406 0.0033365
 S> fm2R <- update( fm2, RML = TRUE )
 Iteration:  0 ,  1  function calls, F=  311.63 
 Parameters:
 [1] -1.02308  0.24935  4.64781
 Iteration:  1 ,  2  function calls, F=  311.62 
 Parameters:
 [1] -1.26615  0.30611  4.49687
 Iteration:  2 ,  3  function calls, F=  311.62 
 Parameters:
 [1] -1.2103  0.2911  4.5384
 Iteration:  3 ,  4  function calls, F=  311.62 
 Parameters:
 [1] -1.20349  0.28932  4.54386
 S> summary( fm2R )
 Call:
   Fixed: distance ~ age * Sex
  Groups:  ~ Subject 
    Data: Orthodont 

 Estimation Method: RML 

 Random effects:
  Level: Subject
  Structure: Unstructured, Matrix Logarithm parametrization
  Formula:  ~ age
  Standard Deviations:
  (Intercept)     age 
       2.4055 0.18035
  Correlation: 
     (Intercept) 
 age -0.66762   


 Within-Group Standard Error: 1.31

 Fixed Effects Estimate(s):
	       Value Std.Error z-value p-value 
 (Intercept)  16.857     0.798  21.127   0.000
	 age   0.632     0.067   9.381   0.000
	 Sex   0.516     0.798   0.647   0.518
     age:Sex  -0.152     0.067  -2.262   0.024

  Correlation of Fixed Effects Estimates 
	 (Intercept)      age      Sex 
     age -0.88016                     
     Sex  0.18519    -0.16299         
 age:Sex -0.16299     0.18519 -0.88016


 Standardized Within-Group Residuals:
      Min       Q1       Med      Q3    Max 
  -3.1681 -0.38594 0.0071041 0.44515 3.8495

 Number of Observations: 108
 Number of Groups: 27 
 S> fm3 <- update( fm2, random = ~ 1 )
 Iteration:  0 ,  1  function calls, F=  313.91 
 Parameters:
 [1] -0.48035
 S> anova( fm2, fm3 )
     Model df    AIC    BIC  logLik Test Lik.Ratio p-value 
 fm2     1  8 443.81 465.26 -213.90                       
 fm3     2  6 440.64 456.73 -214.32        0.83311 0.65932
 S> fm3R <- update( fm3, RML = TRUE )
 Iteration:  0 ,  1  function calls, F=  312.2 
 Parameters:
 [1] -0.54011
 S> summary( fm3R )
 Call:
   Fixed: distance ~ age * Sex
  Groups:  ~ Subject 
    Data: Orthodont 

 Estimation Method: RML 

 Random effects:
  Level: Subject
  Structure: Unstructured, Matrix Logarithm parametrization
  Formula:  ~ 1
  Standard Deviation:
  (Intercept) 
       1.8162


 Within-Group Standard Error: 1.3864

 Fixed Effects Estimate(s):
	       Value Std.Error z-value p-value 
 (Intercept)  16.857     0.769  21.929   0.000
	 age   0.632     0.061  10.409   0.000
	 Sex   0.516     0.769   0.671   0.502
     age:Sex  -0.152     0.061  -2.511   0.012

  Correlation of Fixed Effects Estimates 
	 (Intercept)      age      Sex 
     age -0.86875                     
     Sex  0.18519    -0.16088         
 age:Sex -0.16088     0.18519 -0.86875


 Standardized Within-Group Residuals:
     Min       Q1      Med      Q3    Max 
  -3.598 -0.45462 0.015784 0.50245 3.6862

 Number of Observations: 108
 Number of Groups: 27 
