lapply
Apply a Function to Components of a List or Vector

### Description

Applies a function to components of a list or other object, and then returns the results as a list, a vector, or a matrix.

### Usage

    lapply(X, FUN, ...)
    sapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)
    vapply(X, FUN, FUN.VALUE, ..., USE.NAMES = TRUE)
    simplify2array(x, higher = TRUE)

### Arguments

X | any object; usually a list or vector. Missing values (NAs) are allowed if FUN accepts them.
FUN | a function to apply to the components of X, or a character string giving the name of the function.
FUN.VALUE | a prototype value of what FUN returns. The mode and length of the value is used to determine the result.
... | other arguments to FUN, if any. They can be given with names.
simplify | a logical flag or a character string. If simplify is TRUE (the default), the result is simplified to an array. If simplify is the character string "array", the result is of the form "higher rank", if possible.
USE.NAMES | a logical flag. If TRUE (the default), and if X is a character vector, use X as names for the result, unless names already exist.
x | any object, usually a list, which to be converted to an array.
higher | a logical flag. If TRUE, the result will be "higher rank" array form if possible.

### Details

- lapply: Calls a function for each element of a list and always returns a list.
- sapply: Works like lapply, but then attempts to simplify to a vector or a matrix.
- vapply: The user specifies what the result should look like through FUN.VALUE. Typically, this technique is both more efficient and more predictable.

If the function FUN does not return a compatible value, an error is generated.
These functions are also useful for looping (as an alternative to for) by letting X be a vector such as 1:n. See the examples.
In function simplify2array, if elements of x have different length, returns x; If elements of x have the same length, and the length is 1, returns unlist form of x, if length bigger than 1, simplify each element of x, if higher = TRUE, returns in form "higher rank" if possible. See the examples.
Value

lapply | returns a list like X (the same length and names), where each component of the list is replaced by the result of executing FUN on that component. The components of X are passed as the first argument to FUN not matched by one of the ... arguments.
sapply | returns an object whose first value(s) is (are) the result of FUN applied to the first component of X, and so on. If all results are the same length and simplify is TRUE, sapply returns a matrix with one column for each component. The column names are set from the names of X, and the row names are set from FUN(X[[1]]). If all results are single or numeric values, sapply returns a vector. Otherwise (or if simplify=FALSE), sapply returns a list like lapply.
vapply | returns an object whose first value(s) is (are) the result of FUN applied to the first component of X, and so on. The mode of the object is the same as that of FUN.VALUE. If FUN.VALUE is a vector of length 1, vapply returns a vector. If FUN.VALUE is a vector with length greater than 1, vapply returns a matrix with one column for each value returned by FUN. If FUN.VALUE is a matrix or array, the values from FUN will be combined into a higher-rank array, as when sapply is called with simplify="array". If vapply returns a matrix, the column names are set from the names of X, and the row names are set from FUN(X[[1]]).
simplify2array | returns an array, vector or matrix.

Note

- apply applies a function to specified subsets of a matrix or an array.
- tapply operates on data classified by categorical variables.

References
Becker, R. A., Chambers, J. M., and Wilks, A. R. 1988. The New S Language. Pacific Grove, CA: Wadsworth & Brooks/Cole Advanced Books and Software.
See Also
apply, tapply. rapply. eapply.
Examples

    # generate a list with elements 1, 1:2, 1:3, ...
    lapply(1:5, seq)
    # generate a list with elements 1, c(2, 2), c(3, 3, 3), ...
    lapply(1:5, function(x) rep(x,x))
    # paste the prefix to the elements of LETTERS
    # Here X is used as the second argument to the function!
    lapply(LETTERS, function(pre,post) paste(pre,post), pre="prefix")
    # get list with quantiles for each list element
    lapply(list(a=1:10, b=runif(20)), quantile, probs=1:3/4)
    # get matrix with quantiles for each list element
    sapply(list(a=1:10, b=runif(20)), quantile, probs=1:3/4)
    # Looping using for(), and equivalent loop using sapply and vapply
    result <- rep(NA, 100); for(i in 1:100) result[i] <- sum(1:i)
    result2 <- sapply(1:100, function(i) sum(1:i))
    result3 <- vapply(1:100, function(i) sum(1:i), integer(1))
    # To operate on two lists let X be a vector of indices
    list1 <- lapply(1:6, runif)  # artificial data for this example
    list2 <- lapply(1:6, runif)
    lapply(1:6, function(i, x, y) x[[i]] + y[[i]],
           x = list1, y = list2)
    # Calling lapply() within another function.
    # The internal function f() uses lexical scoping
    # to access the variable myConstant
    addConstant <- function(x, myConstant){
      f <- function(x) x+myConstant
      lapply(x, f)
    }
    addConstant(list(a=1:10, b=seq(1,20,length=5)), 100)
    # Another way to do this, passing the constant as a ... argument
    # to lapply, which is then passed to function f()
    addConstant2 <- function(x, myConstant){
      f <- function(x, y) x+y
      lapply(x, f, myConstant)
    }
    addConstant2(list(a=1:10, b=seq(1,20,length=5)), 100)
    # Be careful with sapply when the input can have length 0
    x <- numeric()
    sapply(x, sin)             # Returns list()
    vapply(x, sin, numeric(1)) # Returns numeric()
    # Generate a matrix with vapply
    vapply(seq(0,pi,len=10), function(x) c(sine=sin(x), cosine=cos(x)), numeric(2))
    # examples for simplify2array
    x <- list(a=c(1, 2), b=1)
    simplify2array(x)
    z<-c(1, 2, 3)
    simplify2array(z)
    y <- list(a = c(1, 2), b = c(3, 4))
    simplify2array(y)
    y.higher <- list(a = matrix(1:2, 1), b = matrix(5:6, 1))
    simplify2array(y.higher)
    simplify2array(y.higher, higher = FALSE)

Package base version 6.1.5-18
Package Index