

   SSuummmmaarriizzee bbyy GGrroouuppss

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

   AArrgguummeennttss::

     object: an object to be summarized - usually a `grouped-
             Data' 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 desig-
             nate 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' func-
             tion, 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 fac-
             tor if necessary, and the unique levels are used
             to define the groups.  Defaults to `for-
             mula(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 corre-
             sponding 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 func-
             tions that are invoked on the variables by group.
             Often it is helpful to specify `na.rm = TRUE'.

   DDeessccrriippttiioonn::

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

   VVaalluuee::

        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'.

   AAuutthhoorr((ss))::

        Jose Pinheiro and Douglas Bates

   SSeeee AAllssoo::

        `summary', `groupedData', `getGroups'

   EExxaammpplleess::

        library( lme )
        data( Orthodont )
        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 )

