future_mapply: Apply a Function to Multiple List or Vector Arguments

Description Usage Arguments Value Author(s) Examples

View source: R/future_mapply.R

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 ... argument, the second elements, the third elements, and so on. Arguments are recycled if necessary.

Usage

1
2
3
4
5
6
future_Map(f, ...)

future_mapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE,
  USE.NAMES = TRUE, future.globals = TRUE, future.packages = NULL,
  future.seed = FALSE, future.lazy = FALSE, future.scheduling = 1,
  future.chunk.size = NULL)

Arguments

f

A function of the arity k if future_Map() is called with k arguments.

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 ... argument has names, or if it is a character vector, use that character vector as the names.

future.globals

A logical, a character vector, or a named list for controlling how globals are handled. For details, see below section.

future.packages

(optional) a character vector specifying packages to be attached in the R environment evaluating the future.

future.seed

A logical or an integer (of length one or seven), or a list of length(X) with pre-generated random seeds. For details, see below section.

future.lazy

Specifies whether the futures should be resolved lazily or eagerly (default).

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 NULL, then argument future.scheduling is used.

...

Arguments to vectorize over (vectors or lists of strictly positive length, or all of zero length).

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 forSIMPLIFY = TRUE', a vector, array or 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
## ---------------------------------------------------------
## 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(multiprocess)
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))

HenrikBengtsson/future.apply documentation built on Aug. 29, 2018, 6:50 a.m.