collapse.groupedData          package:nlme          R Documentation

Collapse a groupedData Object

Description:

     If 'object' has a single grouping factor, it is returned
     unchanged. Else, it is summarized by the values of the
     'displayLevel' grouping factor (or the combination of its values
     and the values of the covariate indicated in 'preserve', if any is
     present). The collapsed data is used to produce a new
     'groupedData' object, with grouping factor given by the
     'displayLevel' factor.

Usage:

     ## S3 method for class 'groupedData':
     collapse(object, collapseLevel, displayLevel,
            outer, inner, preserve, FUN, subset, ...)

Arguments:

  object: an object inheriting from class 'groupedData', generally with
          multiple grouping factors. 

collapseLevel: an optional positive integer or character string
          indicating the grouping level to use when collapsing the
          data. Level values increase from outermost to innermost
          grouping. Default is the highest or innermost level of
          grouping. 

displayLevel: an optional positive integer or character string
          indicating the grouping level to use as the grouping factor
          for the collapsed data. Default is 'collapseLevel'. 

   outer: an optional logical value or one-sided formula, indicating
          covariates that are outer to the 'displayLevel' grouping
          factor. If equal to 'TRUE', the 'displayLevel' element
          'attr(object, "outer")' is used to indicate the  outer
          covariates. 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. Defaults
          to 'NULL', meaning that no outer covariates are to be used. 

   inner: an optional logical value or one-sided formula, indicating a
          covariate that is inner to the 'displayLevel' grouping
          factor. If equal to 'TRUE', 'attr(object, "outer")' is used
          to indicate the inner covariate. An inner covariate can
          change within the sets of rows defined by the grouping 
          factor. Defaults to 'NULL', meaning that no inner covariate
          is present.   

preserve: an optional one-sided formula indicating a covariate whose
          levels should be preserved when collapsing the data according
          to the 'collapseLevel' grouping factor. The collapsing factor
          is obtained by pasting together the levels of the
          'collapseLevel' grouping factor and the values of the
          covariate to be preserved. Default is 'NULL', meaning that no
          covariates need to be preserved. 

     FUN: an optional summary function or a list of summary functions
          to be used for collapsing the data.  The function or
          functions are applied only to variables in 'object' that vary
          within the groups defined by 'collapseLevel'.  Invariant
          variables are  always summarized by group using the unique
          value that they assume within that group.  If 'FUN' is a
          single function it will be applied to each non-invariant
          variable by group to produce the summary for that variable. 
          If 'FUN' is a list of functions, the names in the list should
          designate classes of variables in the data such as 'ordered',
          'factor', or 'numeric'.  The indicated function will be
          applied to any non-invariant variables of that class.  The
          default functions to be used are 'mean' for numeric factors,
          and 'Mode' for both 'factor' and 'ordered'.  The 'Mode'
          function, defined internally in 'gsummary', returns the modal
          or most popular value of the variable.  It is different from
          the 'mode' function that returns the S-language mode of the
          variable.

  subset: an optional named list. Names can be either positive integers
          representing grouping levels, or names of grouping factors.
          Each element in the list is a vector indicating the levels of
          the corresponding grouping factor to be preserved in the
          collapsed data. Default is 'NULL', meaning that all levels
          are used. 

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

Value:

     a 'groupedData' object with a single grouping factor given by the
     'displayLevel' grouping factor, resulting from collapsing 'object'
     over the levels of the 'collapseLevel' grouping factor.

Author(s):

     Jose Pinheiro Jose.Pinheiro@pharma.novartis.com and Douglas Bates
     bates@stat.wisc.edu

See Also:

     'groupedData', 'plot.nmGroupedData'

Examples:

     # collapsing by Dog
     collapse(Pixel, collapse = 1)  # same as collapse(Pixel, collapse = "Dog")

