future.apply: future_mapply – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

future_mapply

Apply a Function to Multiple List or Vector Arguments

Description

future_mapply() implements base::mapply() using futures with perfect replication of results, regardless of future backend used. Analogously to mapply(), future_mapply() is a multivariate version of future_sapply(). It applies FUN to the first elements of each \ldots argument, the second elements, the third elements, and so on. Arguments are recycled if necessary.

Usage

future_Map(f, ..., future.label = "future_Map-%d")

future_mapply(
  FUN,
  ...,
  MoreArgs = NULL,
  SIMPLIFY = TRUE,
  USE.NAMES = TRUE,
  future.stdout = TRUE,
  future.conditions = "condition",
  future.globals = TRUE,
  future.packages = NULL,
  future.lazy = FALSE,
  future.seed = FALSE,
  future.scheduling = 1,
  future.chunk.size = NULL,
  future.label = "future_mapply-%d"
)

future_.mapply(FUN, dots, MoreArgs, ..., future.label = "future_.mapply-%d")

Arguments

`f`	A function of the arity k if `future_Map()` is called with k arguments.
`future.label`	If a character string, then each future is assigned a label `sprintf(future.label, chunk_idx)`. If TRUE, then the same as `future.label = "future_lapply-%d"`. If FALSE, no labels are assigned.
`FUN`	A function to apply, found via `base::match.fun()`.
`MoreArgs`	A list of other arguments to `FUN`.
`SIMPLIFY`	A logical or character string; attempt to reduce the result to a vector, matrix or higher dimensional array; see the simplify argument of `base::sapply()`.
`USE.NAMES`	A logical; use names if the first `\ldots` argument has names, or if it is a character vector, use that character vector as the names.
`future.stdout`	If `TRUE` (default), then the standard output of the underlying futures is captured, and re-outputted as soon as possible. If `FALSE`, any output is silenced (by sinking it to the null device as it is outputted). If `NA` (not recommended), output is not intercepted.
`future.conditions`	A character string of conditions classes to be captured and relayed. The default is the same as the `condition` argument of `future::Future()`. To not intercept conditions, use `conditions = character(0L)`. Errors are always relayed.
`future.globals`	A logical, a character vector, or a named list for controlling how globals are handled. For details, see `future_lapply()`.
`future.packages`	(optional) a character vector specifying packages to be attached in the R environment evaluating the future.
`future.lazy`	Specifies whether the futures should be resolved lazily or eagerly (default).
`future.seed`	A logical or an integer (of length one or seven), or a list of `max(lengths(list(...)))` with pre-generated random seeds. For details, see `future_lapply()`.
`future.scheduling`	Average number of futures ("chunks") per worker. If `0.0`, then a single future is used to process all elements of `X`. If `1.0` or `TRUE`, then one future per worker is used. If `2.0`, then each worker will process two futures (if there are enough elements in `X`). If `Inf` or `FALSE`, then one future per element of `X` is used. Only used if `future.chunk.size` is `NULL`.
`future.chunk.size`	The average number of elements per future ("chunk"). If `Inf`, then all elements are processed in a single future. If `NULL`, then argument `future.scheduling` is used.
`dots`	A list of arguments to vectorize over (vectors or lists of strictly positive length, or all of zero length).
`...`	Arguments to vectorize over (vectors or lists of strictly positive length, or all of zero length).

Details

Note that base::.mapply(), which future_.mapply() is modeled after is listed as an "internal" function in R despite being exported.

Value

future_Map() is a simple wrapper to future_mapply() which does not attempt to simplify the result. See base::Map() for details.

future_mapply() returns a list, or for SIMPLIFY = TRUE, a vector, array or list. See base::mapply() for details.

future_.mapply() returns a list. See base::.mapply() for details.

Author(s)

The implementations of future_Map() is adopted from the source code of the corresponding base R function Map(), which is licensed under GPL (>= 2) with 'The R Core Team' as the copyright holder.

Examples

## ---------------------------------------------------------
## mapply()
## ---------------------------------------------------------
y0 <- mapply(rep, 1:4, 4:1)
y1 <- future_mapply(rep, 1:4, 4:1)
stopifnot(identical(y1, y0))

y0 <- mapply(rep, times = 1:4, x = 4:1)
y1 <- future_mapply(rep, times = 1:4, x = 4:1)
stopifnot(identical(y1, y0))

y0 <- mapply(rep, times = 1:4, MoreArgs = list(x = 42))
y1 <- future_mapply(rep, times = 1:4, MoreArgs = list(x = 42))
stopifnot(identical(y1, y0))

y0 <- mapply(function(x, y) seq_len(x) + y,
             c(a =  1, b = 2, c = 3),  # names from first
             c(A = 10, B = 0, C = -10))
y1 <- future_mapply(function(x, y) seq_len(x) + y,
                    c(a =  1, b = 2, c = 3),  # names from first
                    c(A = 10, B = 0, C = -10))
stopifnot(identical(y1, y0))

word <- function(C, k) paste(rep.int(C, k), collapse = "")
y0 <- mapply(word, LETTERS[1:6], 6:1, SIMPLIFY = FALSE)
y1 <- future_mapply(word, LETTERS[1:6], 6:1, SIMPLIFY = FALSE)
stopifnot(identical(y1, y0))


## ---------------------------------------------------------
## Parallel Random Number Generation
## ---------------------------------------------------------

## Regardless of the future plan, the number of workers, and
## where they are, the random numbers produced are identical

plan(multisession)
y1 <- future_mapply(stats::runif, n = 1:4, max = 2:5,
                    MoreArgs = list(min = 1), future.seed = 0xBEEF)
print(y1)

plan(sequential)
y2 <- future_mapply(stats::runif, n = 1:4, max = 2:5,
                    MoreArgs = list(min = 1), future.seed = 0xBEEF)
print(y2)

stopifnot(all.equal(y1, y2))

future.apply

Apply Function to Elements in Parallel using Futures

v1.7.0

GPL (>= 2)

Authors

Henrik Bengtsson [aut, cre, cph], R Core Team [cph, ctb]

Initial release