Get started with purrr

Progress bars

For long-running jobs, like web scraping, model fitting, or data processing, it’s really useful to get a progress bar that helps you estimate how long you’ll need to wait. Progress bars are easy to enable in purrr: just set .progress = TRUE. It’s hard to illustrate progress bars in a vignette, but you can try this example interactively:

out <- map(1:100, \(i) Sys.sleep(0.5), .progress = TRUE)

Learn more about progress bars in ?progress_bars.

Parallel computing

By default, map() runs only in your current R session. But you can easily opt in to spreading your task across multiple R sessions, and hence multiple cores with in_parallel(). This can give big performance improvements if your task is primarily bound by compute performance.

purrr’s parallelism is powered by mirai, so to begin, you need to start up a number of background R sessions, called daemons:

mirai::daemons(6)

(You only need to do this once per session.)

Now you can easily convert your map() call to run in parallel:

out <- map(1:5, in_parallel(\(i) Sys.sleep(0.5)))

It’s important to realize that this parallelism works by spreading computation across clean R sessions. That means that code like this will not work, because the worker daemons won’t have a copy of my_lm():

my_lm <- function(formula, data) {
  Sys.sleep(0.5)
  lm(formula, data)
}
by_cyl <- split(mtcars, mtcars$cyl)
out <- map(by_cyl, in_parallel(\(df) my_lm(mpg ~ disp, data = df)))
#> Error in `map()`:
#> ℹ In index: 1.
#> ℹ With name: 4.
#> Caused by error in `my_lm()`:
#> ! could not find function "my_lm"

You can resolve this by passing additional data along to in_parallel():

out <- map(by_cyl, in_parallel(\(df) my_lm(mpg ~ disp, data = df), my_lm = my_lm))

Learn more about parallel computing in ?in_parallel.

Output variants

purrr functions are type-stable, which means it’s easy to predict what type of output they return, e.g., map() always returns a list. But what if you want a different type of output? That’s where the output variants come into play:

• There are four variants for the four most important types of atomic vector:

  • map_lgl() returns a logical vector.
  • map_int() returns an integer vector.
  • map_dbl() returns a numeric (double) vector.
  • map_chr() returns a character vector.

• For all other types of vector (like dates, date-times, factors, etc.), there’s map_vec(). It’s a little harder to precisely describe the output type, but if your function returns a length-1 vector of type “foo”, then the output of map_vec() will be a length-n vector of type “foo”.

• modify() returns output with the same type as the input. For example, if the input is a data frame, the output will also be a data frame.

• walk() returns the input (invisibly); it’s useful when you’re calling a function purely for its side effects, for example, generating plots or saving files.

purrr, like many tidyverse functions, is designed to help you solve complex problems by stringing together simple pieces. This is particularly natural to do with the pipe. For example, the following code splits mtcars into one data frame for each value of cyl, fits a linear model to each subset, computes the model summary, and then extracts the R-squared:

mtcars |>
  split(mtcars$cyl) |> # from base R
  map(\(df) lm(mpg ~ wt, data = df)) |>
  map(summary) |>
  map_dbl(\(x) x$r.squared)
#>         4         6         8 
#> 0.5086326 0.4645102 0.4229655

Input variants

map() and friends all iterate over a single list, making it poorly suited for some problems. For example, how would you find a weighted mean when you have a list of observations and a list of weights? Imagine we have the following data:

xs <- map(1:8, ~ runif(10))
xs[[1]][[1]] <- NA
ws <- map(1:8, ~ rpois(10, 5) + 1)

We could use map_dbl() to compute unweighted means:

map_dbl(xs, mean)
#> [1]        NA 0.3940217 0.6221505 0.4176722 0.4016500 0.5058472 0.5201613
#> [8] 0.5138508

But there’s no way to use map() to compute a weighted mean because we need to call weighted.mean(xs[[1]], ws[[1]]), weighted.mean(xs[[2]], ws[[2]]), etc. That’s the job of map2():

map2_dbl(xs, ws, weighted.mean)
#> [1]        NA 0.3793082 0.6352953 0.4286744 0.4067268 0.5487410 0.4804650
#> [8] 0.4702240

Note that the arguments that vary for each call come before the function and arguments that are constant come after the function:

map2_dbl(xs, ws, weighted.mean, na.rm = TRUE)
#> [1] 0.5647890 0.3793082 0.6352953 0.4286744 0.4067268 0.5487410 0.4804650
#> [8] 0.4702240

But we generally recommend using an anonymous function instead, as this makes it very clear where each argument is going:

map2_dbl(xs, ws, \(x, w) weighted.mean(x, w, na.rm = TRUE))

There are two important variants of map2(): pmap() which can take any number of varying arguments (passed as a list), and imap() which iterates over the values and indices of a single vector. Learn more in their documentation.

Combinatorial explosion

What makes purrr particularly special is that all of the above features (progress bars, parallel computing, output variants, and input variants) can be combined any way that you choose. The combination of inputs (prefixes) and outputs (suffixes) forms a matrix, and you can use .progress or in_parallel() with any of them: