plapply: Apply a Function to Multiple List or Vector Arguments

In ArcadeAntics/essentials: Essential Functions not Included in Base R

Apply a Function to Multiple List or Vector Arguments

Description

plapply, psapply, and pvapply are multivariate (parallel) versions of lapply, sapply, and vapply. They take any number of vectors as arguments, recycle them to common length, and return a single vector.

Usage

plapply(X, FUN, ...)

psapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)

pvapply(X, FUN, FUN.VALUE, ..., USE.NAMES = TRUE)

Arguments

X	list of arguments to vectorize over.
FUN	function to apply, found via match.fun.
...	optional arguments to FUN.
simplify	logical or character string; should the result be simplified to a vector, matrix, or higher dimensional array if possible? The default value, TRUE, returns a vector or matrix if appropriate, whereas if simplify = "array" the result may be an array of higher dimension.
USE.NAMES	logical; if TRUE and one of X is character and of equal length to the result, use that element of X as names for the result unless it had names already.
FUN.VALUE	a (generalized) vector; a template for the return value from FUN.

Details

In plapply, after the arguments have been recycled to common length, a list is made with length equal to the common length. The value returned in the j-th position of the list is the function FUN applied to the j-th elements of X, that is:

value[[j]] <- FUN(X[[1L]][[j]], X[[2L]][[j]], ...)

with more or less X[[i]][[j]] depending on the length of X. Additionally, the arguments in the call will be named if X has names.

Unlike lapply, X and its elements will not be coerced by base::as.list. Instead, their subsetting ([[), length, lengths, and names methods will be used.

Simplification in psapply and pvapply is the same as sapply and vapply.

Value

For plapply a list. If any of the input values is a zero-length vector the result has length zero. Otherwise, the result has length equal to the length of the longest vector. Names are copied from input values where possible. Names are only copied from input values whose lengths are equal to the length of the result. If any such input values have a names attribute, the first names attribute is copied to the result.

For psapply a list, the same as plapply. If USE.NAMES and plapply did not give names to its return value, then names are added where possible. If the input values contain a character vector whose length is equal to the length of the result, the names of the the result will be said character vector. Then the result may be simplified to a matrix / / array via simplify2array.

For vapply a vector or array of type matching the FUN.VALUE. If length(FUN.VALUE) == 1 a vector of the common length of X is returned, otherwise an array. If FUN.VALUE is not an array, the result is a matrix with length(FUN.VALUE) rows and common length of X columns, otherwise an array with dim c(dim(FUN.VALUE), <common length of X>)

The (Dim)names of the array value are taken from the 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 X as in psapply.

Note

plapply is based on mapply. The important differences are:

Argument FUN

plapply has FUN as the second argument (same as lapply) while mapply has FUN as the first argument.

Arguments to Vectorize Over

plapply has X as the first argument which is a collection of arguments to vectorize over (same as lapply, aside from the multivariate aspect) while mapply has ... as the collection of arguments to vectorize over. This means you'll need to use do.call or similar if your collection of arguments to vectorize over are already stored in a list, pretty inconvenient.

Optional / / Other / / Further Arguments to FUN

plapply has ... immediately after argument FUN as the additional arguments to provide to FUN each time it is called (same as lapply) while mapply has MoreArgs as the list of additional arguments to provide to FUN. If your additional arguments are already stored in a list, this makes plapply inconvenient to use. However, instead of abandoning plapply in favour of mapply, consider using .plapply, an alternate version that accepts an argument dots instead of ....

More on Additional Arguments to FUN

When using mapply, if MoreArgs contains a symbol or call, it will not be properly protected from early evaluation (despite begging R-Core to change it and even offering a patch :/). I consider this problem big enough that I would never use mapply. It is rare that you'd run into such a scenario, but when you do, it's incredibly hard to debug, and even more annoying to fix while still using mapply. plapply and .plapply have no such issue when ... or dots contains a symbol or call, they will never be evaluated unnecessarily.

See Also

.plapply

Examples

plapply(list(
    col = c("red", "green", "blue"),
    cex = c(1, 1.5, 2),
    main = c("title 1", "title 2", "title 3")
), graphics::plot, x = 1:5, pch = 16)

ArcadeAntics/essentials documentation built on Nov. 7, 2024, 4:33 p.m.