R: Apply a Function to Multiple List or Vector Arguments

future_Map {future.apply} | R Documentation

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

### Usage

    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 for`SIMPLIFY = 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

    ## ---------------------------------------------------------
    ## 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))

[Package future.apply version 1.0.1 Index]