lapply                 package:base                 R Documentation

Apply a Function over a List or Vector

Description:

     'lapply' returns a list of the same length as 'X', each element of
     which is the result of applying 'FUN' to the corresponding element
     of 'X'.

     'sapply' is a user-friendly version of 'lapply' by default
     returning a vector or matrix if appropriate.

     'replicate' is a wrapper for the common use of 'sapply' for
     repeated evaluation of an expression (which will usually involve
     random number generation).

Usage:

     lapply(X, FUN, ...)

     sapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)

     replicate(n, expr, simplify = TRUE)

Arguments:

       X: a vector (atomic or list) or an expressions vector.  Other
          objects (including classed objects) will be coerced by
          'as.list'.

     FUN: the function to be applied to each element of 'X': see
          'Details'.  In the case of functions like '+', '%*%', etc.,
          the function name must be backquoted or quoted.

     ...: optional arguments to 'FUN'.

simplify: logical; should the result be simplified to a vector or
          matrix if possible?

USE.NAMES: logical; if 'TRUE' and if 'X' is character, use 'X' as
          'names' for the result unless it had names already.

       n: number of replications.

    expr: expression (language object, usually a call) to evaluate
          repeatedly.

Details:

     'FUN' is found by a call to 'match.fun' and typically is specified
     as a function or a symbol (e.g. a backquoted name) or a character
     string specifying a function to be searched for from the
     environment of the call to 'lapply'.

     Function 'FUN' must be able to accept as input any of the elements
     of 'X'.  If the latter is an atomic vector, 'FUN' will always be
     passed a length-one vector of the same type as 'X'.

     Simplification in 'sapply' is only attempted if 'X' has length
     greater than zero and if the return values from all elements of
     'X' are all of the same (positive) length.  If the common length
     is one the result is a vector, and if greater than one is a matrix
     with a column corresponding to each element of 'X'.

     The mode of the simplified answer is chosen to accommodate the
     modes of all the values returned by the calls to 'FUN': see
     'unlist'.

     if 'X' has length 0, the return value of 'sapply' is always a
     0-length list.

     Users of S4 classes should pass a list to 'lapply': the internal
     coercion is done by the system 'as.list' in the base namespace and
     not one defined by a user (e.g. by setting S4 methods on the
     system function).

Note:

     'sapply(*, simplify = FALSE, USE.NAMES = FALSE)' is equivalent to
     'lapply(*)'.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'apply', 'tapply', 'mapply' for applying a function to *m*ultiple
     arguments, and 'rapply' for a *r*ecursive version of 'lapply()',
     'eapply' for applying a function to each entry in an
     'environment'.

Examples:

     require(stats); require(graphics)

     x <- list(a = 1:10, beta = exp(-3:3), logic = c(TRUE,FALSE,FALSE,TRUE))
     # compute the list mean for each list element
     lapply(x,mean)
     # median and quartiles for each list element
     lapply(x, quantile, probs = 1:3/4)
     sapply(x, quantile)
     i39 <- sapply(3:9, seq) # list of vectors
     sapply(i39, fivenum)

     hist(replicate(100, mean(rexp(10))))

