gsummary                package:nlme                R Documentation

Summarize by Groups

Description:

     Provide a summary of the variables in a data frame by groups of
     rows. This is most useful with a 'groupedData' object to examine
     the variables by group.

Usage:

     gsummary(object, FUN, omitGroupingFactor, form, level,
        groups, invariantsOnly, ...)

Arguments:

  object: an object to be summarized - usually a 'groupedData' object
          or a 'data.frame'. 

     FUN: an optional summary function or a list of summary functions
          to be applied to each variable in the frame.  The function or
          functions are applied only to variables in 'object' that vary
          within the groups defined by 'groups'.  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 frame 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. 

omitGroupingFactor: an optional logical value.  When 'TRUE' the
          grouping factor itself will be omitted from the group-wise
          summary but the levels of the grouping factor will continue
          to be used as the row names for the data frame that is
          produced by the summary. Defaults to 'FALSE'. 

    form: an optional one-sided formula that defines the groups. When
          this formula is given, the right-hand side is evaluated in
          'object', converted to a factor if necessary, and the unique
          levels are used to define the groups.  Defaults to
          'formula(object)'. 

   level: an optional positive integer giving the level of grouping to
          be used in an object with multiple nested grouping levels.
          Defaults to the highest or innermost level of grouping.

  groups: an optional factor that will be used to split the  rows into
          groups.  Defaults to 'getGroups(object, form, level)'. 

invariantsOnly: an optional logical value.  When 'TRUE' only  those
          covariates that are invariant within each group will be
          summarized.  The summary value for the group is always the
          unique value taken on by that covariate within the group. 
          The columns in the summary are of the same class as the
          corresponding columns in 'object'. By definition, the
          grouping factor itself must be an invariant.   When combined
          with 'omitGroupingFactor = TRUE', this option can be used to
          discover is there are invariant covariates  in the data
          frame.  Defaults to 'FALSE'. 

     ...: optional additional arguments to the summary functions that
          are invoked on the variables by group.  Often it is helpful
          to specify 'na.rm = TRUE'. 

Value:

     A 'data.frame' with one row for each level of the grouping factor.
      The number of columns is at most the number of columns in
     'object'.

Author(s):

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

References:

     Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models in S
     and S-PLUS", Springer.

See Also:

     'summary', 'groupedData', 'getGroups'

Examples:

     gsummary(Orthodont)  # default summary by Subject
     ## gsummary with invariantsOnly = TRUE and omitGroupingFactor = TRUE
     ## determines whether there are covariates like Sex that are invariant
     ## within the repeated observations on the same Subject.
     gsummary(Orthodont, inv = TRUE, omit = TRUE)

