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

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
lapplyreturns 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.
sapplyreturns 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.
vapplyreturns 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
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.4-13
Package Index