| lapply {base} | R Documentation |
Description
lapply returns a list of the same length as X, eachelement of which is the result of applying FUN to thecorresponding element of X.
sapply is a user-friendly version and wrapper of lapplyby default returning a vector, matrix or, if simplify = "array", anarray if appropriate, by applying simplify2array().sapply(x, f, simplify = FALSE, USE.NAMES = FALSE) is the same aslapply(x, f).
vapply is similar to sapply, but has a pre-specifiedtype of return value, so it can be safer (and sometimes faster) touse.
replicate is a wrapper for the common use of sapply forrepeated evaluation of an expression (which will usually involverandom number generation).
simplify2array() is the utility called from sapply()when simplify is not false and is similarly called frommapply().
Usage
lapply(X, FUN, ...)sapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)vapply(X, FUN, FUN.VALUE, ..., USE.NAMES = TRUE)replicate(n, expr, simplify = "array")simplify2array(x, higher = TRUE, except = c(0L, 1L))Arguments
X | a vector (atomic or list) or an |
FUN | the function to be applied to each element of |
... | optional arguments to |
simplify | logical or character string; should the result besimplified to a vector, matrix or higher dimensional array ifpossible? For |
USE.NAMES | logical; if |
FUN.VALUE | a (generalized) vector; a template for the returnvalue 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 |
higher | logical; if true, |
except | integer vector or |
Details
FUN is found by a call to match.fun and typicallyis specified as a function or a symbol (e.g., a backquoted name) or acharacter string specifying a function to be searched for from theenvironment of the call to lapply.
Function FUN must be able to accept as input any of theelements of X. If the latter is an atomic vector, FUNwill always be passed a length-one vector of the same type as X.
Arguments in ... cannot have the same name as any of theother arguments, and care may be needed to avoid partial matching toFUN. In general-purpose code it is good practice to name thefirst two arguments X and FUN if ... is passedthrough: this both avoids partial matching to FUN and ensuresthat a sensible error message is given if arguments named X orFUN are passed through ....
Simplification in sapply is only attempted if X haslength greater than zero and if the return values from all elementsof X are all of the same (positive) length. If the commonlength is one the result is a vector, and if greater than one is amatrix with a column corresponding to each element of X.
Simplification is always done in vapply. This functionchecks that all values of FUN are compatible with theFUN.VALUE, in that they must have the same length and type.(Types may be promoted to a higher type within the ordering logical< integer < double < complex, but not demoted.)
Users of S4 classes should pass a list to lapply andvapply: the internal coercion is done by the as.list inthe base namespace and not one defined by a user (e.g., by setting S4methods on the base function).
Value
For lapply, sapply(simplify = FALSE) andreplicate(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 asX (of length n for replicate). If simplificationoccurs, the output type is determined from the highest type of thereturn values in the hierarchy NULL < raw < logical < integer < double <complex < character < list < expression, after coercion of pairliststo lists.
vapply returns a vector or array of type matching theFUN.VALUE. If length(FUN.VALUE) == 1 avector of the same length as X is returned, otherwisean array. If FUN.VALUE is not an array, theresult is a matrix with length(FUN.VALUE) rows andlength(X) columns, otherwise an array a withdim(a) == c(dim(FUN.VALUE), length(X)).
The (Dim)names of the array value are taken from the FUN.VALUEif it is named, otherwise from the result of the first function call.Column names of the matrix or more generally the names of the lastdimension of the array value or names of the vector value are set fromX as in sapply.
Note
sapply(*, simplify = FALSE, USE.NAMES = FALSE) isequivalent to lapply(*).
For historical reasons, the calls created by lapply areunevaluated, and code has been written (e.g., bquote) thatrelies on this. This means that the recorded call is always of theform FUN(X[[i]], ...), with i replaced by the current(integer or double) index. This is not normally a problem, but it canbe if FUN uses sys.call ormatch.call or if it is a primitive function that makesuse of the call. This means that it is often safer to call primitivefunctions with a wrapper, so that e.g. lapply(ll, function(x) is.numeric(x)) is required to ensure that method dispatch foris.numeric occurs correctly.
If expr is a function call, be aware of assumptions about whereit is evaluated, and in particular what ... might refer to.You can pass additional named arguments to a function call asadditional 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 multiplearguments, and rapply for a recursive version oflapply(), eapply for applying a function to eachentry 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 elementlapply(x, mean)# median and quartiles for each list elementlapply(x, quantile, probs = 1:3/4)sapply(x, quantile)i39 <- sapply(3:9, seq) # list of vectorssapply(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)[Package base version 4.3.0 Index]
