lapply

R Base 3.6.2

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 and wrapper of lapply by default returning a vector, matrix or, if simplify = "array", an array if appropriate, by applying simplify2array(). sapply(x, f, simplify = FALSE, USE.NAMES = FALSE) is the same as lapply(x, f). vapply is similar to sapply, but has a pre-specified type of return value, so it can be safer (and sometimes faster) to use. replicate is a wrapper for the common use of sapply for repeated evaluation of an expression (which will usually involve random number generation). simplify2array() is the utility called from sapply() when simplify is not false and is similarly called from mapply().

Syntax

lapply(X, FUN, &#8230;)<p></p><p>sapply(X, FUN, &#8230;, simplify = TRUE, USE.NAMES = TRUE)</p><p>vapply(X, FUN, FUN.VALUE, &#8230;, USE.NAMES = TRUE)</p><p>replicate(n, expr, simplify = "array")</p><p>simplify2array(x, higher = TRUE)</p>

Arguments

Parameter	Description
`X`	a vector (atomic or list) or an expression object. Other objects (including classed objects) will be coerced by base::as.list.
`FUN`	the function to be applied to each element of X: see ‘Details’. In the case of functions like +, %*%, the function name must be backquoted or quoted.
`…`	optional arguments to FUN.
`simplify`	logical or character string; should the result be simplified to a vector, matrix or higher dimensional array if possible? For sapply it must be named and not abbreviated. The default value, TRUE, returns a vector or matrix if appropriate, whereas if simplify = "array" the result may be an array of “rank” (\(=\)length(dim(.))) one higher than the result of FUN(X[[i]]).
`USE.NAMES`	logical; if TRUE and if X is character, use X as names for the result unless it had names already. Since this argument follows … its name cannot be abbreviated.
`FUN.VALUE`	a (generalized) vector; a template for the return value from FUN. See ‘Details’.
`n`	integer: the number of replications.
`expr`	the expression (a language object, usually a call) to evaluate repeatedly.
`x`	a list, typically returned from lapply().
`higher`	logical; if true, simplify2array() will produce a (“higher rank”) array when appropriate, whereas higher = FALSE would return a matrix (or vector) only. These two cases correspond to sapply(*, simplify = "array") or simplify = TRUE, respectively.

Return Value

For lapply, sapply(simplify = FALSE) and replicate(simplify = FALSE), a list. For sapply(simplify = TRUE) and replicate(simplify = TRUE): 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 < double < complex < character < list < expression, after coercion of p

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. Arguments in … cannot have the same name as any of the other arguments, and care may be needed to avoid partial matching to FUN. In general-purpose code it is good practice to name the first two arguments X and FUN if … is passed through: this both avoids partial matching to FUN and ensures that a sensible error message is given if arguments named X or FUN are passed through …. Simplification in sapp

Examples

Example

# NOT RUN {
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)
vapply(i39, fivenum,
       c(Min. = 0, "1st Qu." = 0, Median = 0, "3rd Qu." = 0, Max. = 0))

## sapply(*, "array") -- artificial example
(v <- structure(10*(5:8), names = LETTERS[1:4]))
f2 <- function(x, y) outer(rep(x, length.out = 3), y)
(a2 <- sapply(v, f2, y = 2*(1:5), simplify = "array"))
a.2 <- vapply(v, f2, outer(1:3, 1:5), y = 2*(1:5))
stopifnot(dim(a2) == c(3,5,4), all.equal(a2, a.2),
          identical(dimnames(a2), list(NULL,NULL,LETTERS[1:4])))

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