# Grouped Data Examples
#
# INTRODUCTION
# This script includes the examples below.
# 1) create groupedData objects, grouping by subject or by dose
# 2) use of inner for a crossover study data (treatment within subject)
# 3) use of outer for two blocking factors (treatment and type)
# 4) misc examples and functions
#
# REFERENCE 
# S-Plus 'Guide to Statistics', Vol 1, Mixed Effect Models
# 'Mixed Effects Modeling Using S and S-Plus' by Pinheiro and Bates
#
# RUNNING THE SCRIPT
# Please refer to the 'GENERAL INSTRUCTIONS' link
# on the website. The data and functions are available
# with S-Plus 2000 for Windows. 
#  
# A groupedData object attaches the formula as an attribute of the data, along
# with inner, outer, units, and label attributes. Several modeling and plot
# methods can be used to construct default plots and models
# The outer and inner parameters can be used for other Blocking factors
# outer - invariant within the grouping factor 
# inner - different levels applied within a grouping factor
#
# to access help on grouped data enter ?groupedData at the command line
?groupedData
# create a Theophylline groupedData object called Theoph.subject, grouping by Subject
Theoph.subject <- # create a new copy of the groupedData object
  groupedData( conc ~ Time | Subject,
              data = Theoph,
              labels = list( x = "Time",
                y = "Conc" ),
              units = list( x = "(hr)", y = "(mg/ml)") )
plot(Theoph.subject)         # trellis plot by subject
### list the formula 
formula(Theoph.subject)
### list the attributes of Theoph
class(Theoph.subject)

# create a Theophylline groupedData object called Theoph.dose, grouping by dose
Theoph.dose <- # create a new copy of the groupedData object
  groupedData( conc ~ Time | Dose,
              data = Theoph,
              inner = ~ Subject,
               labels = list( x = "Time",
                y = "Mean Conc" ),
              units = list( x = "(hr)", y = "(mg/ml)") )
# trellis plot by dose, add 'inner = subject' parameter to distinguish subjects with same dose
# by line color
# inner is used for different levels applied within a grouping factor (in this case, dose)
plot(Theoph.dose,inner = ~ Subject)         

####
# another example, create a grouped data object with log(dose)
formula(PBG)
PBG.log <- update(PBG, formula=deltaBP ~ log(dose) | Rabbit)
formula(PBG.log)
plot(PBG.log)
# Use inner for the different treatments given within a Rabbit,
# where inner - different levels applied within a grouping factor
# this is a crossover study
plot(PBG, inner = ~ Treatment, scales = list(x=list(log=2)))

# another example, plot a grouped data object with outer = Treatment*Type
# where outer is a blocking factor invariant within the grouping factor 
#CO2
plot(CO2)
#outer ~Treatment*Type
plot(CO2, outer=T)

# another example 
Orth.new <-  # create a new copy of the groupedData object
  groupedData( distance ~ age | Subject,
              data = as.data.frame( Orthodont ),
              FUN = mean,
              outer = ~ Sex,
              labels = list( x = "Age",
                y = "Distance from pituitary to pterygomaxillary fissure" ),
              units = list( x = "(yr)", y = "(mm)") )
plot( Orth.new )         # trellis plot by Subject
formula( Orth.new )      # extractor for the formula
gsummary( Orth.new )     # apply summary by Subject
fm1 <- lme( Orth.new )   # fixed and groups formulae extracted from object