lapply {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`.

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

### Value

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.

### Note

`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’.

### 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 multiple arguments, and `rapply` for a recursive 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))))

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

[Package base version 2.8.1 Index]