gapply                 package:nlme                 R Documentation

Apply a Function by Groups

Description:

     Applies the function to the distinct sets of rows of the data
     frame defined by 'groups'.

Usage:

     gapply(object, which, FUN, form, level, groups, ...)

Arguments:

  object: an object to which the function will be applied - usually a
          'groupedData' object or a 'data.frame'. Must inherit from
          class 'data.frame'. 

   which: an optional character or positive integer vector specifying
          which columns of 'object' should be used with 'FUN'. Defaults
          to all columns in 'object'. 

     FUN: function to apply to the distinct sets of rows of the data
          frame 'object' defined by the values of 'groups'. 

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

     ...: optional additional arguments to the summary function 'FUN'. 
          Often it is helpful to specify 'na.rm = TRUE'. 

Value:

     Returns a data frame with as many rows as there are levels in the
     'groups' argument.

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, esp. sec. 3.4.

See Also:

     'gsummary'

Examples:

     ## Find number of non-missing "conc" observations for each Subject
     gapply( Phenobarb, FUN = function(x) sum(!is.na(x$conc)) )

     # Pinheiro and Bates, p. 127 
     table( gapply(Quinidine, "conc", function(x) sum(!is.na(x))) )
     changeRecords <- gapply( Quinidine, FUN = function(frm)
         any(is.na(frm[["conc"]]) & is.na(frm[["dose"]])) )

