Map over a list while capturing side effects.

Source: R/wrappers.r

map_safely(), map_quietly() and map_peacefully() are variants of purrr::map() that wrap the supplied function .f using purrr::safely() and/or purrr::quietly() in order to capture various side effects. Lists mapped in this way have an associated class added to them, allowing them to succinctly summarise captured side effects when displayed in a tibble.

map_safely(.x, .f, otherwise = NULL, quiet = TRUE, ...)

map_quietly(.x, .f, ...)

map_peacefully(.x, .f, ...)

map2_safely(.x, .y, .f, otherwise = NULL, quiet = TRUE, ...)

map2_quietly(.x, .y, .f, ...)

map2_peacefully(.x, .y, .f, ...)

pmap_safely(.l, .f, otherwise = NULL, quiet = TRUE, ...)

pmap_quietly(.l, .f, ...)

pmap_peacefully(.l, .f, ...)

future_map_safely(.x, .f, otherwise = NULL, quiet = TRUE, ...)

future_map_quietly(.x, .f, ...)

future_map_peacefully(.x, .f, ...)

future_map2_safely(.x, .y, .f, otherwise = NULL, quiet = TRUE, ...)

future_map2_quietly(.x, .y, .f, ...)

future_map2_peacefully(.x, .y, .f, ...)

future_pmap_safely(.l, .f, otherwise = NULL, quiet = TRUE, ...)

future_pmap_quietly(.l, .f, ...)

future_pmap_peacefully(.l, .f, ...)

Arguments

.x

A list or atomic vector.
.f

A function, formula or atomic vector, as specified by purrr::as_mapper().
otherwise

Default value to use when an error occurs.
quiet

Hide errors (TRUE, the default), or display them as they occur?
...

Other arguments supplied to purrr::map() or its variants, or to furrr::future_map() or its variants..
.y

A list or atomic vector, of the same length as .x.
.l

A list of lists. The length of .l determines the number of arguments that .f will be called with. List names will be used if present.

Value

A list of the same length as .x. Each element of the returned list is itself a named list, structured according to the captured side effects. The Details section elaborates on these side effects.

Details

map_safely() will summarise the returned list with a fixed-width string of two (spaced) columns:

  1. If a result component is present, R appears, and

  2. If an error component is present, E appears.

If either component is missing, an underscore (_) appears in its place.

Similarly, map_quietly() will summarise the returned list with a fixed-width string of four (spaced) columns:

  1. If a result component is present, R appears,

  2. If an output component is present, O appears,

  3. If a messages component is present, M appears, and

  4. If a warnings component is present, W appears.

If any is missing, an underscore (_) appears in its place.

Variants for iterating over two or more inputs simultaneously are also provided and function identically to their purrr counterparts:

  1. map2_safely()

  2. map2_quietly()

  3. pmap_safely()

  4. pmap_quietly()

Further variants, prefixed by future_, allow safe or quiet mapping to happen in parallel if you have the furrr package installed:

  1. future_map_safely()

  2. future_map_quietly()

  3. future_map2_safely()

  4. future_map2_quietly()

  5. future_pmap_safely()

  6. future_pmap_quietly()

Examples


library(tibble)
library(dplyr)

#> 
#> Attaching package: ‘dplyr’
#> The following objects are masked from ‘package:stats’:
#> 
#>     filter, lag
#> The following objects are masked from ‘package:base’:
#> 
#>     intersect, setdiff, setequal, union
library(tidyr)
library(collateral)

# like map(), these can be used to iterate over vectors or lists
list("a", 10, 100) %>% map_safely(log)

#> _ E
#> R _
#> R _
list(5, -12, 103) %>% map_quietly(log)

#> R _ _ _
#> R _ _ W
#> R _ _ _

# if you're using tibbles, you can also iterate over list-columns,
# such as nested data frames
mtcars %>%
  rownames_to_column(var = "car") %>%
  as_tibble() %>%
  select(car, cyl, disp, wt) %>%
  # spike some rows in cyl == 4 to make them fail
  mutate(wt = dplyr::case_when(
    wt < 2 ~ -wt,
    TRUE ~ wt)) %>%
  # nest and do some operations quietly()
  nest(data = -cyl) %>%
  mutate(qlog = map_quietly(data, ~ log(.$wt)))

#> # A tibble: 3 x 3
#>     cyl data              qlog    
#>   <dbl> <list>            <collat>
#> 1     6 <tibble [7 × 3]>  R _ _ _ 
#> 2     4 <tibble [11 × 3]> R _ _ W 
#> 3     8 <tibble [14 × 3]> R _ _ _