foreach               package:foreach               R Documentation

_f_o_r_e_a_c_h

_D_e_s_c_r_i_p_t_i_o_n:

     '%do%' and '%dopar%' are binary operators that operate on a
     'foreach' object and an 'R' expression. The expression, 'ex', is
     evaluated multiple times in an environment that is created by the
     'foreach' object, and that environment is modified for each
     evaluation as specified by the 'foreach' object. '%do%' evaluates
     the expression sequentially, while '%dopar%' evalutes it in
     parallel. The results of evaluating 'ex' are returned as a list by
     default, but this can be modified by means of the '.combine'
     argument.

_U_s_a_g_e:

     foreach(..., .combine, .init, .final=NULL, .inorder=TRUE,
            .multicombine=FALSE,
            .maxcombine=if (.multicombine) 100 else 2,
            .errorhandling=c('stop', 'remove', 'pass'),
            .packages=NULL, .export=NULL, .noexport=NULL,
            .verbose=FALSE)
     when(cond)
     e1 %:% e2
     obj %do% ex
     obj %dopar% ex
     times(n)

_A_r_g_u_m_e_n_t_s:

     ...: one or more arguments that control how 'ex' is evaluated. 
          Named arguments specify the name and values of variables to
          be defined in the evaluation environment. An unnamed argument
          can be used to specify the number of times that 'ex' should
          be evaluated. At least one argument must be specified in
          order to define the number of times 'ex' should be executed.

.combine: function that is used to process the tasks results as they
          generated.  This can be specified as either a function or a
          non-empty character string naming the function. Specifying
          'c' is useful for concatenating the results into a vector,
          for example.  The values 'cbind' and 'rbind' can combine
          vectors into a matrix.  The values '+' and '*' can be used to
          process numeric data. By default, the results are returned in
          a list.

   .init: initial value to pass as the first argument of the '.combine'
          function. This should not be specified unless '.combine' is
          also specified.

  .final: function of one argument that is called to return final
          result.

.inorder: logical flag indicating whether the '.combine' function
          requires the task results to be combined in the same order
          that they were submitted.  If the order is not important,
          then it setting '.inorder' to 'FALSE' can give improved
          performance. The default value is 'TRUE'.

.multicombine: logical flag indicating whether the '.combine' function
          can accept more than two arguments. If an arbitrary
          '.combine' function is specified, by default, that function
          will always be called with two arguments. If it can take more
          than two arguments, then setting '.multicombine' to 'TRUE'
          could improve the performance. The default value is 'FALSE'
          unless the '.combine' function is 'cbind', 'rbind', or 'c',
          which are known to take more than two arguments.

.maxcombine: maximum number of arguments to pass to the combine
          function. This is only relevant if '.multicombine' is 'TRUE'.

.errorhandling: specifies how a task evalution error should be handled.
          If the value is "stop", then execution will be stopped via
          the 'stop' function if an error occurs. If the value is
          "remove", the result for that task will not be returned, or
          passed to the '.combine' function. If it is "pass", then the
          error object generated by task evaluation will be included
          with the rest of the results.  It is assumed that the combine
          function (if specified) will be able to deal with the error
          object. The default value is "stop".

.packages: character vector of packages that the tasks depend on. If
          'ex' requires a 'R' package to be loaded, this option can be
          used to load that package on each of the workers. Ignored
          when used with '%do%'.

 .export: character vector of variables to export. This can be useful
          when accessing a variable that isn't defined in the current
          environment. The default value in 'NULL'.

.noexport: character vector of variables to exclude from exporting.
          This can be useful to prevent variables from being exported
          that aren't actually needed, perhaps because the symbol is
          used in a model formula. The default value in 'NULL'.

.verbose: logical flag enabling verbose messages.  This can be very
          useful for trouble shooting.

     obj: 'foreach' object used to control the evaluation of 'ex'.

      e1: 'foreach' object to merge.

      e2: 'foreach' object to merge.

      ex: the 'R' expression to evaluate.

    cond: condition to evaluate.

       n: number of times to evaluate the 'R' expression.

_D_e_t_a_i_l_s:

     The 'foreach' and '%do%'/'%dopar%' operators provide a looping
     construct that can be viewed as a hybrid of the standard 'for'
     loop and 'lapply' function. It looks similar to the 'for' loop,
     and it evaluates an expression, rather than a function (as in
     'lapply'), but it's purpose is to return a value (a list, by
     default), rather than to cause side-effects. This faciliates
     parallelization, but looks more natural to people that prefer
     'for' loops to 'lapply'.

     Parallel computation depends upon a _parallel backend_ that must
     be  registered before performing the computation. The parallel
     backends available will be system-specific, but include 'doNWS',
     which uses the NetWorkSpaces parallelization system, 'doMC', which
     uses the 'multicore' package, and 'doSNOW'. Each parallel backend
     has a specific registration function, such as 'registerDoNWS' or
     'registerDoSNOW'.

     The 'times' function is a simple convenience function that calls
     'foreach'.  It is useful for evaluating an 'R' expression multiple
     times when there are no varying arguments.  This can be convenient
     for resampling, for example.

_S_e_e _A_l_s_o:

     'iter'

_E_x_a_m_p_l_e_s:

     # equivalent to rnorm(3)
     times(3) %do% rnorm(1)

     # equivalent to lapply(1:3, sqrt)
     foreach(i=1:3) %do%
       sqrt(i)

     # equivalent to colMeans(m)
     m <- matrix(rnorm(9), 3, 3)
     foreach(i=1:ncol(m), .combine=c) %do%
       mean(m[,i])

     # normalize the rows of a matrix in parallel, with parenthesis used to
     # force proper operator precedence
     # Need to register a parallel backend before this example will run
     # in parallel
     foreach(i=1:nrow(m), .combine=rbind) %dopar%
       (m[i,] / mean(m[i,]))

     # simple (and inefficient) parallel matrix multiply
     a <- matrix(1:16, 4, 4)
     b <- t(a)
     foreach(b=iter(b, by='col'), .combine=cbind) %dopar%
       (a %*% b)

     # split a data frame by row, and put them back together again without
     # changing anything
     d <- data.frame(x=1:10, y=rnorm(10))
     s <- foreach(d=iter(d, by='row'), .combine=rbind) %dopar% d
     identical(s, d)

     # a quick sort function
     qsort <- function(x) {
       n <- length(x)
       if (n == 0) {
         x
       } else {
         p <- sample(n, 1)
         smaller <- foreach(y=x[-p], .combine=c) %:% when(y <= x[p]) %do% y
         larger  <- foreach(y=x[-p], .combine=c) %:% when(y >  x[p]) %do% y
         c(qsort(smaller), x[p], qsort(larger))
       }
     }
     qsort(runif(12))

