Package 'purrr' reference manual

Title:	Functional Programming Tools
Description:	A complete and consistent functional programming toolkit for R.
Authors:	Hadley Wickham [aut, cre] , Lionel Henry [aut], Posit Software, PBC [cph, fnd]
Maintainer:	Hadley Wickham <[email protected]>
License:	MIT + file LICENSE
Version:	1.0.2.9000
Built:	2024-05-09 07:00:01 UTC
Source:	https://github.com/tidyverse/purrr

Accumulate intermediate results of a vector reduction

Description

accumulate() sequentially applies a 2-argument function to elements of a vector. Each application of the function uses the initial value or result of the previous application as the first argument. The second argument is the next value of the vector. The results of each application are returned in a list. The accumulation can optionally terminate before processing the whole vector in response to a done() signal returned by the accumulation function.

By contrast to accumulate(), reduce() applies a 2-argument function in the same way, but discards all results except that of the final function application.

accumulate2() sequentially applies a function to elements of two lists, .x and .y.

Usage

accumulate(
  .x,
  .f,
  ...,
  .init,
  .dir = c("forward", "backward"),
  .simplify = NA,
  .ptype = NULL
)

accumulate2(.x, .y, .f, ..., .init, .simplify = NA, .ptype = NULL)

Arguments

`.x`	A list or atomic vector.
`.f`	For `accumulate()` `.f` is 2-argument function. The function will be passed the accumulated result or initial value as the first argument. The next value in sequence is passed as the second argument. For `accumulate2()`, a 3-argument function. The function will be passed the accumulated result as the first argument. The next value in sequence from `.x` is passed as the second argument. The next value in sequence from `.y` is passed as the third argument. The accumulation terminates early if `.f` returns a value wrapped in a `done()`.
`...`	Additional arguments passed on to the mapped function. We now generally recommend against using `...` to pass additional (constant) arguments to `.f`. Instead use a shorthand anonymous function: # Instead of x \|> map(f, 1, 2, collapse = ",") # do: x \|> map(\(x) f(x, 1, 2, collapse = ",")) This makes it easier to understand which arguments belong to which function and will tend to yield better error messages.
`.init`	If supplied, will be used as the first value to start the accumulation, rather than using `.x[[1]]`. This is useful if you want to ensure that `reduce` returns a correct value when `.x` is empty. If missing, and `.x` is empty, will throw an error.
`.dir`	The direction of accumulation as a string, one of `"forward"` (the default) or `"backward"`. See the section about direction below.
`.simplify`	If `NA`, the default, the accumulated list of results is simplified to an atomic vector if possible. If `TRUE`, the result is simplified, erroring if not possible. If `FALSE`, the result is not simplified, always returning a list.
`.ptype`	If `simplify` is `NA` or `TRUE`, optionally supply a vector prototype to enforce the output type.
`.y`	For `accumulate2()` `.y` is the second argument of the pair. It needs to be 1 element shorter than the vector to be accumulated (`.x`). If `.init` is set, `.y` needs to be one element shorted than the concatenation of the initial value and `.x`.

Value

A vector the same length of .x with the same names as .x.

If .init is supplied, the length is extended by 1. If .x has names, the initial value is given the name ".init", otherwise the returned vector is kept unnamed.

If .dir is "forward" (the default), the first element is the initial value (.init if supplied, or the first element of .x) and the last element is the final reduced value. In case of a right accumulation, this order is reversed.

The accumulation terminates early if .f returns a value wrapped in a done(). If the done box is empty, the last value is used instead and the result is one element shorter (but always includes the initial value, even when terminating at the first iteration).

Life cycle

accumulate_right() is soft-deprecated in favour of the .dir argument as of rlang 0.3.0. Note that the algorithm has slightly changed: the accumulated value is passed to the right rather than the left, which is consistent with a right reduction.

Direction

When .f is an associative operation like + or c(), the direction of reduction does not matter. For instance, reducing the vector 1:3 with the binary function + computes the sum ((1 + 2) + 3) from the left, and the same sum (1 + (2 + 3)) from the right.

In other cases, the direction has important consequences on the reduced value. For instance, reducing a vector with list() from the left produces a left-leaning nested list (or tree), while reducing list() from the right produces a right-leaning list.

Examples

# With an associative operation, the final value is always the
# same, no matter the direction. You'll find it in the first element for a
# backward (left) accumulation, and in the last element for forward
# (right) one:
1:5 |> accumulate(`+`)
1:5 |> accumulate(`+`, .dir = "backward")

# The final value is always equal to the equivalent reduction:
1:5 |> reduce(`+`)

# It is easier to understand the details of the reduction with
# `paste()`.
accumulate(letters[1:5], paste, sep = ".")

# Note how the intermediary reduced values are passed to the left
# with a left reduction, and to the right otherwise:
accumulate(letters[1:5], paste, sep = ".", .dir = "backward")

# By ignoring the input vector (nxt), you can turn output of one step into
# the input for the next. This code takes 10 steps of a random walk:
accumulate(1:10, \(acc, nxt) acc + rnorm(1), .init = 0)

# `accumulate2()` is a version of `accumulate()` that works with
# 3-argument functions and one additional vector:
paste2 <- function(acc, nxt, sep = ".") paste(acc, nxt, sep = sep)
letters[1:4] |> accumulate(paste2)
letters[1:4] |> accumulate2(c("-", ".", "-"), paste2)

# You can shortcircuit an accumulation and terminate it early by
# returning a value wrapped in a done(). In the following example
# we return early if the result-so-far, which is passed on the LHS,
# meets a condition:
paste3 <- function(out, input, sep = ".") {
  if (nchar(out) > 4) {
    return(done(out))
  }
  paste(out, input, sep = sep)
}
letters |> accumulate(paste3)

# Note how we get twice the same value in the accumulation. That's
# because we have returned it twice. To prevent this, return an empty
# done box to signal to accumulate() that it should terminate with the
# value of the last iteration:
paste3 <- function(out, input, sep = ".") {
  if (nchar(out) > 4) {
    return(done())
  }
  paste(out, input, sep = sep)
}
letters |> accumulate(paste3)

# Here the early return branch checks the incoming inputs passed on
# the RHS:
paste4 <- function(out, input, sep = ".") {
  if (input == "f") {
    return(done())
  }
  paste(out, input, sep = sep)
}
letters |> accumulate(paste4)


# Simulating stochastic processes with drift
## Not run: 
library(dplyr)
library(ggplot2)

map(1:5, \(i) rnorm(100)) |>
  set_names(paste0("sim", 1:5)) |>
  map(\(l) accumulate(l, \(acc, nxt) .05 + acc + nxt)) |>
  map(\(x) tibble(value = x, step = 1:100)) |>
  list_rbind(id = "simulation") |>
  ggplot(aes(x = step, y = value)) +
    geom_line(aes(color = simulation)) +
    ggtitle("Simulations of a random walk with drift")

## End(Not run)

Apply a function to each element of a vector

Description

The map functions transform their input by applying a function to each element of a list or atomic vector and returning an object of the same length as the input.

map() always returns a list. See the modify() family for versions that return an object of the same type as the input.
map_lgl(), map_int(), map_dbl() and map_chr() return an atomic vector of the indicated type (or die trying). For these functions, .f must return a length-1 vector of the appropriate type.
map_vec() simplifies to the common type of the output. It works with most types of simple vectors like Date, POSIXct, factors, etc.
walk() calls .f for its side-effect and returns the input .x.

Usage

map(.x, .f, ..., .progress = FALSE)

map_lgl(.x, .f, ..., .progress = FALSE)

map_int(.x, .f, ..., .progress = FALSE)

map_dbl(.x, .f, ..., .progress = FALSE)

map_chr(.x, .f, ..., .progress = FALSE)

map_vec(.x, .f, ..., .ptype = NULL, .progress = FALSE)

walk(.x, .f, ..., .progress = FALSE)

Arguments

`.x`	A list or atomic vector.
`.f`	A function, specified in one of the following ways: A named function, e.g. `mean`. An anonymous function, e.g. `⁠\(x) x + 1⁠` or `function(x) x + 1`. A formula, e.g. `~ .x + 1`. You must use `.x` to refer to the first argument. Only recommended if you require backward compatibility with older versions of R. A string, integer, or list, e.g. `"idx"`, `1`, or `list("idx", 1)` which are shorthand for `⁠\(x) pluck(x, "idx")⁠`, `⁠\(x) pluck(x, 1)⁠`, and `⁠\(x) pluck(x, "idx", 1)⁠` respectively. Optionally supply `.default` to set a default value if the indexed element is `NULL` or does not exist.
`...`	Additional arguments passed on to the mapped function. We now generally recommend against using `...` to pass additional (constant) arguments to `.f`. Instead use a shorthand anonymous function: # Instead of x \|> map(f, 1, 2, collapse = ",") # do: x \|> map(\(x) f(x, 1, 2, collapse = ",")) This makes it easier to understand which arguments belong to which function and will tend to yield better error messages.
`.progress`	Whether to show a progress bar. Use `TRUE` to turn on a basic progress bar, use a string to give it a name, or see progress_bars for more details.
`.ptype`	If `NULL`, the default, the output type is the common type of the elements of the result. Otherwise, supply a "prototype" giving the desired type of output.

Value

The output length is determined by the length of the input. The output names are determined by the input names. The output type is determined by the suffix:

No suffix: a list; .f() can return anything.
⁠_lgl()⁠, ⁠_int()⁠, ⁠_dbl()⁠, ⁠_chr()⁠ return a logical, integer, double, or character vector respectively; .f() must return a compatible atomic vector of length 1.
⁠_vec()⁠ return an atomic or S3 vector, the same type that .f returns. .f can return pretty much any type of vector, as long as its length 1.
walk() returns the input .x (invisibly). This makes it easy to use in a pipe. The return value of .f() is ignored.

Any errors thrown by .f will be wrapped in an error with class purrr_error_indexed.

Examples

# Compute normal distributions from an atomic vector
1:10 |>
  map(rnorm, n = 10)

# You can also use an anonymous function
1:10 |>
  map(\(x) rnorm(10, x))

# Simplify output to a vector instead of a list by computing the mean of the distributions
1:10 |>
  map(rnorm, n = 10) |>  # output a list
  map_dbl(mean)           # output an atomic vector

# Using set_names() with character vectors is handy to keep track
# of the original inputs:
set_names(c("foo", "bar")) |> map_chr(paste0, ":suffix")

# Working with lists
favorite_desserts <- list(Sophia = "banana bread", Eliott = "pancakes", Karina = "chocolate cake")
favorite_desserts |> map_chr(\(food) paste(food, "rocks!"))

# Extract by name or position
# .default specifies value for elements that are missing or NULL
l1 <- list(list(a = 1L), list(a = NULL, b = 2L), list(b = 3L))
l1 |> map("a", .default = "???")
l1 |> map_int("b", .default = NA)
l1 |> map_int(2, .default = NA)

# Supply multiple values to index deeply into a list
l2 <- list(
  list(num = 1:3,     letters[1:3]),
  list(num = 101:103, letters[4:6]),
  list()
)
l2 |> map(c(2, 2))

# Use a list to build an extractor that mixes numeric indices and names,
# and .default to provide a default value if the element does not exist
l2 |> map(list("num", 3))
l2 |> map_int(list("num", 3), .default = NA)

# Working with data frames
# Use map_lgl(), map_dbl(), etc to return a vector instead of a list:
mtcars |> map_dbl(sum)

# A more realistic example: split a data frame into pieces, fit a
# model to each piece, summarise and extract R^2
mtcars |>
  split(mtcars$cyl) |>
  map(\(df) lm(mpg ~ wt, data = df)) |>
  map(summary) |>
  map_dbl("r.squared")

`array`	An array to coerce into a list.
`margin`	A numeric vector indicating the positions of the indices to be to be enlisted. If `NULL`, a full margin is used. If `numeric(0)`, the array as a whole is wrapped in a list.

`x`	A list. For `list_rbind()` and `list_cbind()` the list must only contain only data frames or `NULL`.
`...`	These dots are for future extensions and must be empty.
`ptype`	An optional prototype to ensure that the output type is always the same.
`name_repair`	One of `"unique"`, `"universal"`, or `"check_unique"`. See `vctrs::vec_as_names()` for the meaning of these options.
`size`	An optional integer size to ensure that every input has the same size (i.e. number of rows).
`names_to`	By default, `names(x)` are lost. To keep them, supply a string to `names_to` and the names will be saved into a column with that name. If `names_to` is supplied and `x` is not named, the position of the elements will be used instead of the names.

`x`	A list.
`...`	These dots are for future extensions and must be empty.
`name_spec`	If both inner and outer names are present, control how they are combined. Should be a glue specification that uses variables `inner` and `outer`.
`name_repair`	One of `"minimal"`, `"unique"`, `"universal"`, or `"check_unique"`. See `vctrs::vec_as_names()` for the meaning of these options.

`x`	A list.
`...`	These dots are for future extensions and must be empty.
`strict`	What should happen if simplification fails? If `TRUE`, it will error. If `FALSE` and `ptype` is not supplied, it will return `x` unchanged.
`ptype`	An optional prototype to ensure that the output type is always the same.

`x`	A list of vectors to transpose.
`...`	These dots are for future extensions and must be empty.
`template`	A "template" that describes the output list. Can either be a character vector (where elements are extracted by name), or an integer vector (where elements are extracted by position). Defaults to the names of the first element of `x`, or if they're not present, the integer indices.
`simplify`	Should the result be simplified? `TRUE`: simplify or die trying. `NA`: simplify if possible. `FALSE`: never try to simplify, always leaving as a list. Alternatively, a named list specifying the simplification by output element.
`ptype`	An optional vector prototype used to control the simplification. Alternatively, a named list specifying the prototype by output element.
`default`	A default value to use if a value is absent or `NULL`. Alternatively, a named list specifying the default by output element.

`.x`	A list or vector.
`.f`	A function, specified in one of the following ways: A named function, e.g. `mean`. An anonymous function, e.g. `⁠\(x) x + 1⁠` or `function(x) x + 1`. A formula, e.g. `~ .x + 1`. You must use `.x` to refer to the first argument. Only recommended if you require backward compatibility with older versions of R. A string, integer, or list, e.g. `"idx"`, `1`, or `list("idx", 1)` which are shorthand for `⁠\(x) pluck(x, "idx")⁠`, `⁠\(x) pluck(x, 1)⁠`, and `⁠\(x) pluck(x, "idx", 1)⁠` respectively. Optionally supply `.default` to set a default value if the indexed element is `NULL` or does not exist.
`...`	Additional arguments passed on to `.p`.
`.dir`	If `"forward"`, the default, starts at the beginning of the vector and move towards the end; if `"backward"`, starts at the end of the vector and moves towards the beginning.
`.right`	Please use `.dir` instead.
`.default`	The value returned when nothing is detected.

`.x`	A list or data frame.
`.f`	A function that takes a length-1 list and returns a list (of any length.)
`...`	Additional arguments passed on to the mapped function. We now generally recommend against using `...` to pass additional (constant) arguments to `.f`. Instead use a shorthand anonymous function: # Instead of x \|> map(f, 1, 2, collapse = ",") # do: x \|> map(\(x) f(x, 1, 2, collapse = ",")) This makes it easier to understand which arguments belong to which function and will tend to yield better error messages.
`.p`	A single predicate function, a formula describing such a predicate function, or a logical vector of the same length as `.x`. Alternatively, if the elements of `.x` are themselves lists of objects, a string indicating the name of a logical element in the inner lists. Only those elements where `.p` evaluates to `TRUE` will be modified.
`.else`	A function applied to elements of `.x` for which `.p` returns `FALSE`.
`.at`	A logical, integer, or character vector giving the elements to select. Alternatively, a function that takes a vector of names, and returns a logical, integer, or character vector of elements to select. : if the tidyselect package is installed, you can use `vars()` and tidyselect helpers to select elements.

`.x`	A list or atomic vector.
`.depth`	Level of `.x` to map on. Use a negative value to count up from the lowest level of the list. `map_depth(x, 0, fun)` is equivalent to `fun(x)`. `map_depth(x, 1, fun)` is equivalent to `x <- map(x, fun)` `map_depth(x, 2, fun)` is equivalent to `⁠x <- map(x, \(y) map(y, fun))⁠`
`.f`	A function, specified in one of the following ways: A named function, e.g. `mean`. An anonymous function, e.g. `⁠\(x) x + 1⁠` or `function(x) x + 1`. A formula, e.g. `~ .x + 1`. You must use `.x` to refer to the first argument. Only recommended if you require backward compatibility with older versions of R. A string, integer, or list, e.g. `"idx"`, `1`, or `list("idx", 1)` which are shorthand for `⁠\(x) pluck(x, "idx")⁠`, `⁠\(x) pluck(x, 1)⁠`, and `⁠\(x) pluck(x, "idx", 1)⁠` respectively. Optionally supply `.default` to set a default value if the indexed element is `NULL` or does not exist.
`...`	Additional arguments passed on to the mapped function. We now generally recommend against using `...` to pass additional (constant) arguments to `.f`. Instead use a shorthand anonymous function: # Instead of x \|> map(f, 1, 2, collapse = ",") # do: x \|> map(\(x) f(x, 1, 2, collapse = ",")) This makes it easier to understand which arguments belong to which function and will tend to yield better error messages.
`.ragged`	If `TRUE`, will apply to leaves, even if they're not at depth `.depth`. If `FALSE`, will throw an error if there are no elements at depth `.depth`.
`.is_node`	A predicate function that determines whether an element is a node (by returning `TRUE`) or a leaf (by returning `FALSE`). The default value, `NULL`, treats simple lists as nodes and everything else (including richer objects like data frames and linear models) as leaves, using `vctrs::vec_is_list()`. To recurse into all objects built on lists use `is.list()`.

`.x`, `.y`	A pair of vectors, usually the same length. If not, a vector of length 1 will be recycled to the length of the other.
`.f`	A function, specified in one of the following ways: A named function. An anonymous function, e.g. `⁠\(x, y) x + y⁠` or `function(x, y) x + y`. A formula, e.g. `~ .x + .y`. You must use `.x` to refer to the current element of `x` and `.y` to refer to the current element of `y`. Only recommended if you require backward compatibility with older versions of R.
`...`	Additional arguments passed on to the mapped function. We now generally recommend against using `...` to pass additional (constant) arguments to `.f`. Instead use a shorthand anonymous function: # Instead of x \|> map(f, 1, 2, collapse = ",") # do: x \|> map(\(x) f(x, 1, 2, collapse = ",")) This makes it easier to understand which arguments belong to which function and will tend to yield better error messages.
`.progress`	Whether to show a progress bar. Use `TRUE` to turn on a basic progress bar, use a string to give it a name, or see progress_bars for more details.
`.ptype`	If `NULL`, the default, the output type is the common type of the elements of the result. Otherwise, supply a "prototype" giving the desired type of output.

`.x`	A vector.
`.f`	A function specified in the same way as the corresponding map function.
`...`	Additional arguments passed on to the mapped function. We now generally recommend against using `...` to pass additional (constant) arguments to `.f`. Instead use a shorthand anonymous function: # Instead of x \|> map(f, 1, 2, collapse = ",") # do: x \|> map(\(x) f(x, 1, 2, collapse = ",")) This makes it easier to understand which arguments belong to which function and will tend to yield better error messages.
`.p`	A single predicate function, a formula describing such a predicate function, or a logical vector of the same length as `.x`. Alternatively, if the elements of `.x` are themselves lists of objects, a string indicating the name of a logical element in the inner lists. Only those elements where `.p` evaluates to `TRUE` will be modified.
`.else`	A function applied to elements of `.x` for which `.p` returns `FALSE`.
`.at`	A logical, integer, or character vector giving the elements to select. Alternatively, a function that takes a vector of names, and returns a logical, integer, or character vector of elements to select. : if the tidyselect package is installed, you can use `vars()` and tidyselect helpers to select elements.
`.y`	A vector, usually the same length as `.x`.

`.x`, `x`	A vector or environment
`.where`, `where`	A pluck location, as a numeric vector of positions, a character vector of names, or a list combining both. The location must exist in the data structure.
`.f`	A function to apply at the pluck location given by `.where`.
`...`	Arguments passed to `.f`.
`value`	A value to replace in `.x` at the pluck location. Use `zap()` to instead remove the element.

`x`	A list.
`...`	Reserved for future use. Must be empty
`leaf`	A function applied to each leaf.
`is_node`	A predicate function that determines whether an element is a node (by returning `TRUE`) or a leaf (by returning `FALSE`). The default value, `NULL`, treats simple lists as nodes and everything else (including richer objects like data frames and linear models) as leaves, using `vctrs::vec_is_list()`. To recurse into all objects built on lists use `is.list()`.
`pre`, `post`	Functions applied to each node. `pre` is applied on the way "down", i.e. before the leaves are transformed with `leaf`, while `post` is applied on the way "up", i.e. after the leaves are transformed.

`.f`	a function. For the output source to read well, this should be a named function.
`...`	named arguments to `.f` that should be partially applied. Pass an empty `⁠... = ⁠` argument to specify the position of future arguments relative to partialised ones. See `rlang::call_modify()` to learn more about this syntax. These dots support quasiquotation. If you unquote a value, it is evaluated only once at function creation time. Otherwise, it is evaluated each time the function is called.
`.env`	The environments are now captured via quosures.
`.lazy`	Please unquote the arguments that should be evaluated once at function creation time with `⁠!!⁠`.
`.first`	Please pass an empty argument `⁠... = ⁠` to specify the position of future arguments.

`x`	A vector
`is_node`	Optionally override the default criteria for determine an element can be recursed within. The default matches the behaviour of `pluck()` which can recurse into lists and expressions.

`.l`	A list of vectors. The length of `.l` determines the number of arguments that `.f` will be called with. Arguments will be supply by position if unnamed, and by name if named. Vectors of length 1 will be recycled to any length; all other elements must be have the same length. A data frame is an important special case of `.l`. It will cause `.f` to be called once for each row.
`.f`	A function, specified in one of the following ways: A named function. An anonymous function, e.g. `⁠\(x, y, z) x + y / z⁠` or `function(x, y, z) x + y / z` A formula, e.g. `~ ..1 + ..2 / ..3`. This syntax is not recommended as you can only refer to arguments by position.
`...`	Additional arguments passed on to the mapped function. We now generally recommend against using `...` to pass additional (constant) arguments to `.f`. Instead use a shorthand anonymous function: # Instead of x \|> map(f, 1, 2, collapse = ",") # do: x \|> map(\(x) f(x, 1, 2, collapse = ",")) This makes it easier to understand which arguments belong to which function and will tend to yield better error messages.
`.progress`	Whether to show a progress bar. Use `TRUE` to turn on a basic progress bar, use a string to give it a name, or see progress_bars for more details.
`.ptype`	If `NULL`, the default, the output type is the common type of the elements of the result. Otherwise, supply a "prototype" giving the desired type of output.

`pause`	Delay between attempts in seconds.
`max_times`	Maximum number of requests to attempt.
`pause_base`, `pause_cap`	`rate_backoff()` uses an exponential back-off so that each request waits `pause_base * 2^i` seconds, up to a maximum of `pause_cap` seconds.
`pause_min`	Minimum time to wait in the backoff; generally only necessary if you need pauses less than one second (which may not be kind to the server, use with caution!).
`jitter`	Whether to introduce a random jitter in the waiting time.
`x`	An object to test.

Package 'purrr'

Help Index

Accumulate intermediate results of a vector reduction

Description

Usage

Arguments

Value

Life cycle

Direction

See Also

Examples

Coerce array to list

Description

Usage

Arguments

Details

Examples

Convert an object into a mapper function

Description

Usage

Arguments

Examples

Create an attribute getter function

Description

Usage

Arguments

See Also

Examples

Wrap a function so it will automatically browse() on error

Description

Usage

Arguments

Value

Adverbs

See Also

Examples

Get an element deep within a nested data structure, failing if it doesn't exist

Description

Usage

Arguments

See Also

Examples

Compose multiple functions together to create a new function

Description

Usage

Arguments

Value

Adverbs

See Also

Examples

Find the value or position of the first match

Description

Usage

Arguments

Value

See Also

Examples

Do every, some, or none of the elements of a list satisfy a predicate?

Description

Usage

Arguments

Value

Examples

Does a list contain an object?

Description

Usage

Arguments

Examples

Find head/tail that all satisfies a predicate.

Description

Usage

Arguments

Value

Examples

Apply a function to each element of a vector, and its index

Description

Usage

Arguments

Value

See Also

Wrap a function so it will automatically `browse()` on error