by                   package:base                   R Documentation

Apply a Function to a Data Frame split by Factors

Description:

     Function 'by' is an object-oriented wrapper for 'tapply' applied
     to data frames.

Usage:

     by(data, INDICES, FUN, ..., simplify = TRUE)

Arguments:

    data: an R object, normally a data frame, possibly a matrix.

 INDICES: a factor or a list of factors, each of length 'nrow(data)'.

     FUN: a function to be applied to data frame subsets of 'data'.

     ...: further arguments to 'FUN'.

simplify: logical: see 'tapply'.

Details:

     A data frame is split by row into data frames subsetted by the
     values of one or more factors, and function 'FUN' is applied to
     each subset in turn.

     Object 'data' will be coerced to a data frame by the default
     method, _but_ if this results in a 1-column data frame, the
     objects passed to 'FUN' are dropped to a subsets of that column.
     (This was the long-term behaviour, but only documented since R
     2.7.0.)

Value:

     An object of class '"by"', giving the results for each subset.
     This is always a list if 'simplify' is false, otherwise a list or
     array (see 'tapply').

See Also:

     'tapply'

Examples:

     require(stats)
     attach(warpbreaks)
     by(warpbreaks[, 1:2], tension, summary)
     by(warpbreaks[, 1], list(wool = wool, tension = tension), summary)
     by(warpbreaks, tension, function(x) lm(breaks ~ wool, data = x))

     ## now suppose we want to extract the coefficients by group
     tmp <- by(warpbreaks, tension, function(x) lm(breaks ~ wool, data = x))
     sapply(tmp, coef)

     detach("warpbreaks")

