| % File src/library/base/man/lapply.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2014 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{lapply} |
| \title{Apply a Function over a List or Vector} |
| \alias{lapply} |
| \alias{sapply} |
| \alias{vapply} |
| \alias{replicate} |
| \alias{simplify2array} |
| \usage{ |
| lapply(X, FUN, \dots) |
| |
| sapply(X, FUN, \dots, simplify = TRUE, USE.NAMES = TRUE) |
| |
| vapply(X, FUN, FUN.VALUE, \dots, USE.NAMES = TRUE) |
| |
| replicate(n, expr, simplify = "array") |
| |
| simplify2array(x, higher = TRUE) |
| } |
| \arguments{ |
| \item{X}{a vector (atomic or list) or an \code{\link{expression}} |
| object. Other objects (including classed objects) will be coerced |
| by \code{base::\link{as.list}}.} |
| \item{FUN}{the function to be applied to each element of \code{X}: |
| see \sQuote{Details}. In the case of functions like |
| \code{+}, \code{\%*\%}, the function name must be backquoted or quoted.} |
| \item{\dots}{optional arguments to \code{FUN}.} |
| \item{simplify}{logical or character string; should the result be |
| simplified to a vector, matrix or higher dimensional array if |
| possible? For \code{sapply} it must be named and not abbreviated. |
| The default value, \code{TRUE}, returns a vector or matrix if appropriate, |
| whereas if \code{simplify = "array"} the result may be an |
| \code{\link{array}} of \dQuote{rank} |
| (\eqn{=}\code{length(dim(.))}) one higher than the result |
| of \code{FUN(X[[i]])}.} |
| \item{USE.NAMES}{logical; if \code{TRUE} and if \code{X} is character, |
| use \code{X} as \code{\link{names}} for the result unless it had names |
| already. Since this argument follows \code{\dots} its name cannot |
| be abbreviated.} |
| \item{FUN.VALUE}{a (generalized) vector; a template for the return |
| value from FUN. See \sQuote{Details}.} |
| \item{n}{integer: the number of replications.} |
| \item{expr}{the expression (a \link{language object}, usually a call) |
| to evaluate repeatedly.} |
| |
| \item{x}{a list, typically returned from \code{lapply()}.} |
| \item{higher}{logical; if true, \code{simplify2array()} will produce a |
| (\dQuote{higher rank}) array when appropriate, whereas |
| \code{higher = FALSE} would return a matrix (or vector) only. |
| These two cases correspond to \code{sapply(*, simplify = "array")} or |
| \code{simplify = TRUE}, respectively.} |
| } |
| \description{ |
| \code{lapply} returns a list of the same length as \code{X}, each |
| element of which is the result of applying \code{FUN} to the |
| corresponding element of \code{X}. |
| |
| \code{sapply} is a user-friendly version and wrapper of \code{lapply} |
| by default returning a vector, matrix or, if \code{simplify = "array"}, an |
| array if appropriate, by applying \code{simplify2array()}. |
| \code{sapply(x, f, simplify = FALSE, USE.NAMES = FALSE)} is the same as |
| \code{lapply(x, f)}. |
| |
| \code{vapply} is similar to \code{sapply}, but has a pre-specified |
| type of return value, so it can be safer (and sometimes faster) to |
| use. |
| |
| \code{replicate} is a wrapper for the common use of \code{sapply} for |
| repeated evaluation of an expression (which will usually involve |
| random number generation). |
| |
| \code{simplify2array()} is the utility called from \code{sapply()} |
| when \code{simplify} is not false and is similarly called from |
| \code{\link{mapply}()}. |
| } |
| \details{ |
| \code{FUN} is found by a call to \code{\link{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 \code{lapply}. |
| |
| Function \code{FUN} must be able to accept as input any of the |
| elements of \code{X}. If the latter is an atomic vector, \code{FUN} |
| will always be passed a length-one vector of the same type as \code{X}. |
| |
| Arguments in \code{\dots} cannot have the same name as any of the |
| other arguments, and care may be needed to avoid partial matching to |
| \code{FUN}. In general-purpose code it is good practice to name the |
| first two arguments \code{X} and \code{FUN} if \code{\dots} is passed |
| through: this both avoids partial matching to \code{FUN} and ensures |
| that a sensible error message is given if arguments named \code{X} or |
| \code{FUN} are passed through \code{\dots}. |
| |
| Simplification in \code{sapply} is only attempted if \code{X} has |
| length greater than zero and if the return values from all elements |
| of \code{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 \code{X}. |
| |
| Simplification is always done in \code{vapply}. This function |
| checks that all values of \code{FUN} are compatible with the |
| \code{FUN.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 \code{lapply} and |
| \code{vapply}: the internal coercion is done by the \code{as.list} in |
| the base namespace and not one defined by a user (e.g., by setting S4 |
| methods on the base function). |
| %% rather should really use as(x, "list") iff isS4(x) |
| |
| \code{lapply} and \code{vapply} are \link{primitive} functions. |
| } |
| \value{ |
| For \code{lapply}, \code{sapply(simplify = FALSE)} and |
| \code{replicate(simplify = FALSE)}, a list. |
| |
| For \code{sapply(simplify = TRUE)} and \code{replicate(simplify = |
| TRUE)}: if \code{X} has length zero or \code{n = 0}, an empty list. |
| Otherwise an atomic vector or matrix or list of the same length as |
| \code{X} (of length \code{n} for \code{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 pairlists |
| to lists. |
| |
| \code{vapply} returns a vector or array of type matching the |
| \code{FUN.VALUE}. If \code{length(FUN.VALUE) == 1} a |
| vector of the same length as \code{X} is returned, otherwise |
| an array. If \code{FUN.VALUE} is not an \code{\link{array}}, the |
| result is a matrix with \code{length(FUN.VALUE)} rows and |
| \code{length(X)} columns, otherwise an array \code{a} with |
| \code{\link{dim}(a) == c(dim(FUN.VALUE), length(X))}. |
| |
| The (Dim)names of the array value are taken from the \code{FUN.VALUE} |
| if it is named, otherwise from the result of the first function call. |
| Column names of the matrix or more generally the names of the last |
| dimension of the array value or names of the vector value are set from |
| \code{X} as in \code{sapply}. |
| } |
| \note{ |
| \code{sapply(*, simplify = FALSE, USE.NAMES = FALSE)} is |
| equivalent to \code{lapply(*)}. |
| |
| For historical reasons, the calls created by \code{lapply} are |
| unevaluated, and code has been written (e.g., \code{bquote}) that |
| relies on this. This means that the recorded call is always of the |
| form \code{FUN(X[[i]], ...)}, with \code{i} replaced by the current |
| (integer or double) index. This is not normally a problem, but it can |
| be if \code{FUN} uses \code{\link{sys.call}} or |
| \code{\link{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.\sspace{}\code{lapply(ll, function(x) |
| is.numeric(x))} is required to ensure that method dispatch for |
| \code{is.numeric} occurs correctly. |
| |
| If \code{expr} is a function call, be aware of assumptions about where |
| it is evaluated, and in particular what \code{\dots} might refer to. |
| You can pass additional named arguments to a function call as |
| additional named arguments to \code{replicate}: see \sQuote{Examples}. |
| } |
| \references{ |
| Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. |
| } |
| \seealso{ |
| \code{\link{apply}}, \code{\link{tapply}}, |
| \code{\link{mapply}} for applying a function to \bold{m}ultiple |
| arguments, and \code{\link{rapply}} for a \bold{r}ecursive version of |
| \code{lapply()}, \code{\link{eapply}} for applying a function to each |
| entry in an \code{\link{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) |
| 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) |
| } |
| % taken from PR#8472 |
| \keyword{iteration} |
| \keyword{list} |