$Id: EXAMPLES,v 1.3 1999/05/27 22:08:41 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 )
 R> fm1 <-
 +  lme( distance ~ age, data = Orthodont, control = list(msVerbose = TRUE))
 iteration = 0
 Step:
 [1] 0 0 0
 Parameter:
 [1] -0.310048  0.099647  2.060363
 Function Value
 [1] 318.18
 Gradient:
 [1]  0.37270 -0.85388  0.21007

 iteration = 1
 Step:
 [1] -0.0038938  0.0089209 -0.0021947
 Parameter:
 [1] -0.31394  0.10857  2.05817
 Function Value
 [1] 318.17
 Gradient:
 [1] 0.56391 0.41507 0.45974

 iteration = 2
 Step:
 [1] -0.0078728  0.0019304 -0.0057764
 Parameter:
 [1] -0.32181  0.11050  2.05239
 Function Value
 [1] 318.16
 Gradient:
 [1] 0.56016 0.35242 0.39387

 iteration = 3
 Step:
 [1] -0.194130  0.052015 -0.129566
 Parameter:
 [1] -0.51595  0.16251  1.92283
 Function Value
 [1] 318.14
 Gradient:
 [1]  0.6952  2.3961 -1.3401

 iteration = 4
 Step:
 [1]  0.081420 -0.031517  0.063376
 Parameter:
 [1] -0.43452  0.13100  1.98620
 Function Value
 [1] 318.11
 Gradient:
 [1]  0.38911 -0.71103 -0.49975

 iteration = 5
 Step:
 [1] -0.0276243  0.0071485 -0.0103079
 Parameter:
 [1] -0.46215  0.13815  1.97589
 Function Value
 [1] 318.1
 Gradient:
 [1]  0.40001 -0.27578 -0.54621

 iteration = 6
 Step:
 [1] -0.083143  0.016965 -0.019667
 Parameter:
 [1] -0.54529  0.15511  1.95623
 Function Value
 [1] 318.08
 Gradient:
 [1]  0.28137  0.75519 -0.54700

 iteration = 7
 Step:
 [1] -0.0087727 -0.0011740  0.0088409
 Parameter:
 [1] -0.55407  0.15394  1.96507
 Function Value
 [1] 318.08
 Gradient:
 [1]  0.17162  0.45750 -0.33450

 iteration = 8
 Step:
 [1] -0.0139423 -0.0017714  0.0138473
 Parameter:
 [1] -0.56801  0.15217  1.97891
 Function Value
 [1] 318.07
 Gradient:
 [1] -0.0091035 -0.0057939 -0.0105693

 iteration = 9
 Step:
 [1]  0.00318437 -0.00047508  0.00112543
 Parameter:
 [1] -0.56482  0.15169  1.98004
 Function Value
 [1] 318.07
 Gradient:
 [1] 0.00221566 0.00033134 0.00070821

 iteration = 10
 Parameter:
 [1] -0.56540  0.15178  1.97989
 Function Value
 [1] 318.07
 Gradient:
 [1] 2.5172e-05 1.8250e-04 4.0882e-05

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

 R> summary( fm1 )
 Linear mixed-effects model fit by REML
  Data: Orthodont 
      AIC    BIC  logLik
   454.64 470.62 -221.32

 Random effects:
  Formula: ~age | Subject
  Structure: General positive-definite
	     StdDev  Corr  
 (Intercept) 2.32264 (Intr)
 age         0.22599 -0.607
 Residual    1.31001       

 Fixed effects: distance ~ age 
	       Value Std.Error DF t-value p-value
 (Intercept) 16.7611   0.77474 80 21.6344  <.0001
 age          0.6602   0.07120 80  9.2722  <.0001
  Correlation: 
     (Intr)
 age -0.848

 Standardized Within-Group Residuals:
	Min         Q1        Med         Q3        Max 
 -3.2265528 -0.4937565  0.0074885  0.4725589  3.9162073 

 Number of Observations: 108
 Number of Groups: 27 
 R> fm2 <- lme( distance ~ age * Sex, data = Orthodont,
 +              random = ~ age | Subject )
 R> summary( fm2 )
 Linear mixed-effects model fit by REML
  Data: Orthodont 
      AIC    BIC  logLik
   448.58 469.74 -216.29

 Random effects:
  Formula: ~age | Subject
  Structure: General positive-definite
	     StdDev  Corr  
 (Intercept) 2.39544 (Intr)
 age         0.17927 -0.664
 Residual    1.31039       

 Fixed effects: distance ~ age * Sex 
	       Value Std.Error DF t-value p-value
 (Intercept) 16.3406   1.01723 79 16.0639  <.0001
 age          0.7844   0.08588 79  9.1339  <.0001
 Sex          1.0321   1.59369 25  0.6476  0.5231
 age.Sex     -0.3048   0.13454 79 -2.2657  0.0262
  Correlation: 
	 (Intr) age    Sex   
 age     -0.880              
 Sex     -0.638  0.561       
 age.Sex  0.561 -0.638 -0.880

 Standardized Within-Group Residuals:
	Min         Q1        Med         Q3        Max 
 -3.1746856 -0.3874747  0.0065163  0.4465357  3.8487146 

 Number of Observations: 108
 Number of Groups: 27 
 R> anova(fm2)  # Wald tests for significance of fixed-effects terms
	     numDF denDF F-value p-value
 (Intercept)     1    79  4027.5  <.0001
 age             1    79    99.7  <.0001
 Sex             1    25     8.0  0.0091
 age:Sex         1    79     5.1  0.0262
 R> fm3 <- update( fm2, random = ~ 1 )
 R> fm3
 Linear mixed-effects model fit by REML
   Data: Orthodont 
   Log-restricted-likelihood: -216.88
   Fixed: distance ~ age * Sex 
 (Intercept)         age         Sex     age.Sex 
    16.34063     0.78438     1.03210    -0.30483 

 Random effects:
  Formula: ~1 | Subject
	 (Intercept) Residual
 StdDev:      1.8162   1.3864

 Number of Observations: 108
 Number of Groups: 27 
 R> anova( fm2, fm3 ) # likelihood ratio tests for random-effects
     Model df    AIC    BIC  logLik   Test L.Ratio p-value
 fm2     1  8 448.58 469.74 -216.29                       
 fm3     2  6 445.76 461.62 -216.88 1 vs 2  1.1754  0.5556
