groupedData               package:nlme               R Documentation

Construct a groupedData Object

Description:

     An object of the 'groupedData' class is constructed from the
     'formula' and 'data' by attaching the 'formula' as an attribute of
     the data, along with any of 'outer', 'inner', 'labels', and
     'units' that are given.  If 'order.groups' is 'TRUE' the grouping
     factor is converted to an ordered factor with the ordering
     determined by 'FUN'. Depending on the number of grouping levels
     and the type of primary covariate, the returned object will be of
     one of three classes: 'nfnGroupedData' - numeric covariate, single
     level of nesting; 'nffGroupedData' - factor covariate, single
     level of nesting; and 'nmGroupedData' - multiple levels of
     nesting. Several modeling and plotting functions can use the
     formula stored with a 'groupedData' object to construct default
     plots and models.

Usage:

     groupedData(formula, data, order.groups, FUN, outer, inner,
      labels, units)
     ## S3 method for class 'groupedData':
     update(object, formula, data, order.groups, FUN,
     outer, inner, labels, units, ...)

Arguments:

  object: an object inheriting from class 'groupedData'.

 formula: a formula of the form 'resp ~ cov | group' where 'resp' is
          the response, 'cov' is the primary covariate, and 'group' is
          the grouping factor.  The expression '1' can be used for the
          primary covariate when there is no other suitable candidate. 
          Multiple nested grouping factors can be listed separated by
          the '/' symbol as in 'fact1/fact2'.  In an expression like
          this the 'fact2' factor is nested within the 'fact1' factor.

    data: a data frame in which the expressions in 'formula' can be
          evaluated.  The resulting 'groupedData' object will consist
          of the same data values in the same order but with additional
          attributes.

order.groups: an optional logical value, or list of logical values,
          indicating if the grouping factors should be converted to
          ordered factors according to the function 'FUN' applied to
          the response from each group. If multiple levels of grouping
          are present, this argument can be either a single logical
          value (which will be repeated for all grouping levels) or a
          list of logical values. If no names are assigned to the list
          elements, they are assumed in the same order as the group
          levels (outermost to innermost grouping). Ordering within a
          level of grouping is done within the levels of the grouping
          factors which are outer to it. Changing the grouping factor
          to an ordered factor does not affect the ordering of the rows
          in the data frame but it does affect the order of the panels
          in a trellis display of the data or models fitted to the
          data.  Defaults to 'TRUE'.

     FUN: an optional summary function that will be applied to the
          values of the response for each level of the grouping factor,
          when 'order.groups = TRUE', to determine the ordering. 
          Defaults to the 'max' function.

   outer: an optional one-sided formula, or list of one-sided formulas,
          indicating covariates that are outer to the grouping
          factor(s).  If multiple levels of grouping are present, this
          argument can be either a single one-sided formula, or a list
          of one-sided formulas. If no names are assigned to the list
          elements, they are assumed in the same order as the group
          levels (outermost to innermost grouping). An outer covariate
          is invariant within the sets of rows defined by the grouping
          factor.  Ordering of the groups is done in such a way as to
          preserve adjacency of groups with the same value of the outer
          variables.  When plotting a  groupedData object, the argument
          'outer = TRUE' causes the panels to be determined by the
          'outer' formula.  The points within the panels are 
          associated by level of the grouping factor. Defaults to
          'NULL', meaning that no outer covariates are present.

   inner: an optional one-sided formula, or list of one-sided formulas,
          indicating covariates that are inner to the grouping
          factor(s). If multiple levels of grouping are present, this
          argument can be either a single one-sided formula, or a list
          of one-sided formulas. If no names are assigned to the list
          elements, they are assumed in the same order as the group
          levels (outermost to innermost grouping). An inner covariate
          can change  within the sets of rows defined by the grouping
          factor.  An inner formula can be used to associate points in
          a plot of a groupedData object.  Defaults to 'NULL', meaning
          that no inner covariates are present.

  labels: an optional list of character strings giving labels for the
          response and the primary covariate.  The label for the
          primary covariate is named 'x' and that for the response is
          named 'y'.  Either label can be omitted.

   units: an optional list of character strings giving the units for
          the response and the primary covariate.  The units string for
          the primary covariate is named 'x' and that for the response
          is named 'y'.  Either units string can be omitted.

     ...: some methods for this generic require additional arguments. 
          None are used in this method.

Value:

     an object of one of the classes 'nfnGroupedData',
     'nffGroupedData', or 'nmGroupedData', and also inheriting from 
     classes 'groupedData' and 'data.frame'.

Author(s):

     Douglas Bates and Jose Pinheiro

References:

     Bates, D.M. and Pinheiro, J.C. (1997), "Software Design for
     Longitudinal Data", in "Modelling Longitudinal and Spatially
     Correlated Data: Methods, Applications and Future Directions",
     T.G. Gregoire (ed.), Springer-Verlag, New York.

     Pinheiro, J.C. and Bates, D.M. (1997) "Future Directions in
     Mixed-Effects Software: Design of NLME 3.0" available at
     http://nlme.stat.wisc.edu/

See Also:

     'formula', 'gapply', 'gsummary', 'lme'

Examples:

     data(Orthodont)
     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)") )
     ## Not run: 
     plot( Orth.new )         # trellis plot by Subject
     ## End(Not run)
     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
     Orthodont2 <- update(Orthodont, FUN = mean)

