nws (version 1.7.0.0)

eachElem: Apply a Function in Parallel over a Set of Lists and Vectors

Description

eachElem executes function fun multiple times in parallel with a varying set of arguments, and returns the results in a list. It is functionally similar to the standard R lapply function, but is more flexible in the way that the function arguments can be specified.

Usage

## S3 method for class 'sleigh':
eachElem(.Object, fun, elementArgs=list(), fixedArgs=list(), 
      eo=NULL, DEBUG=FALSE)

Arguments

.Object

sleigh class object.

fun

the function to be evaluated by the sleigh. In the case of functions like +, %*%, etc., the function name must be quoted.

elementArgs

list of vectors, lists, matrices, and data frames that specify (some of) the arguments to be passed to fun. Each element should correspond to an argument of fun.

fixedArgs

list of additional arguments to be passed to fun. Each element should correspond to an argument of fun.

eo

list specifying environment options. See the section Environment Options below.

DEBUG

logical; should browser function be called upon entry to eachElem? The default is FALSE.

Details

The eachElem function forms argument sets from objects passed in via elementArgs and fixedArgs. The elements of elementsArgs are used to specify the arguments that are changing, or varying, from task to task, while the elements of fixedArgs are used to specify the arguments that do not vary from task to task. The number of tasks that are executed by a call to eachElem is basically equal to the length of the longest vector (or list, etc) in elementArgs. If any elements of elementArgs are shorter, then their values are recycled, using the standard R rules.

The elements of elementArgs may be vectors, lists, matrices, or data frames. The vectors and lists are always iterated over by element, or "cell", but matrices and data frames can also be iterated over by row or column. This is controlled by the by option, specified via the eo argument. See below for more information.

For example: eachElem(s, '+', elementArgs=list(1:4), fixedArgs=list(100)) This will submit four tasks, since the length of 1:4 is four. The four tasks will be to add the arguments 1 and 100, 2 and 100, 3 and 100, and 4 and 100. The result is a list containing the four values 101, 102, 103, and 104.

Another way to do the same thing is with: eachElem(s, '+', elementArgs=list(1:4, 100)) Since the second element of elementArgs is length one, it's value is recycled four times, thus specifying the same set of tasks as in the previous example. This method also has the advantage of making it easy to put fixed values before varying values, without the need for the eo$argPermute option, discussed later. For example: eachElem(s, '-', elementArgs=list(100, 1:4))

is similar to the R statement:

100 - 1:4

Note that in simple examples like these, where the results are numeric values, the standard R unlist function can be very useful for converting the resulting list into a vector.

See Also

eachWorker, sleighPending

Examples

# create a sleigh
s <- sleigh()

# compute the list mean for each list element
x <- list(a=1:10, beta=exp(-3:3), logic=c(TRUE,FALSE,FALSE,TRUE))
eachElem(s, mean, list(x))

# median and quartiles for each list element
eachElem(s, quantile, elementArgs=list(x), fixedArgs=list(probs=1:3/4))

# use eo$elementFunc to supply 100 random values and eo$accumulator to
# receive the results
elementFunc <- function(i, by) {
  if (i <= 100) list(i=i, x=runif(1)) else stop()
}
accumulator <- function(resultList, taskVector) {
  if (resultList[[1]][[1]] != taskVector[1]) stop('assertion failure')
  cat(paste(resultList[[1]], collapse=' '), '\n')
}
eo <- list(elementFunc=elementFunc, accumulator=accumulator)
eachElem(s, function(i, x) list(i=i, x=x, xsq=x*x), eo=eo)