lapply                 package:base                 R Documentation

_A_p_p_l_y _a _F_u_n_c_t_i_o_n _o_v_e_r _a _L_i_s_t _o_r _V_e_c_t_o_r

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     lapply(X, FUN, ...)

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

     replicate(n, expr, simplify = TRUE)

_A_r_g_u_m_e_n_t_s:

       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.

_D_e_t_a_i_l_s:

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

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

_V_a_l_u_e:

     For 'lapply' and 'sapply(simplify=FALSE)', a list.

     For 'sapply(simplify=TRUE)' and 'replicate': if 'X' has length
     zero or 'n = 0', an empty list.  Otherwise an atomic vector or
     matrix or list of the same length as 'X' (of length 'n' for
     'replicate').  If simplification occurs, the output type is
     determined from the highest type of the return values in the
     hierarchy NULL < raw < logical < integer < real < complex <
     character < list < expression, after coercion of pairlists
     tolists.

_N_o_t_e:

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

     For historical reasons, the calls created by 'lapply' are
     unevaluated, and code has been written (e.g. 'bquote') that relies
     on this.  This means that the recorded call is always of the form
     'FUN(X[[0L]], ...)', with '0L' replaced by the current integer
     index.  This not normally a problem, but it can be if 'FUN' uses
     'sys.call' or 'match.call' or if it is a primitive function that
     makes use of the call.  This means that it is often safer to call
     primitive functions with a wrapper, so that e.g. 'lapply(ll,
     function(x) is.numeric(x))' is required in R 2.7.1 to ensure that
     method dispatch for 'is.numeric' occurs correctly.

     If 'expr' is a function call, be aware of assumptions about where
     it is evaluated, and in particular what '...' might refer to. You
     can pass additional named arguments to a function call as
     additional named arguments to 'replicate': see 'Examples'.

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

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

     ## use of replicate() with parameters:
     foo <- function(x=1, y=2) c(x,y)
     # does not work: bar <- function(n, ...) replicate(n, foo(...))
     bar <- function(n, x) replicate(n, foo(x=x))
     bar(5, x=3)