map() in R: purrr map, Map() and Variants

Q: What is the difference between map() and Map()?

map() (purrr) works over one list or vector. Map() (base R) works over the corresponding elements of several vectors, and cannot take constant extra arguments. For two or more inputs, purrr’s equivalents are map2() and pmap() .

map() in R applies a function to every element of a list or vector and returns the results. In the purrr package, map() always returns a list, and typed siblings such as map_dbl() return a plain vector of one type. Base R’s capital-M Map() does a related job over several vectors at once. This guide covers all three, and spells out what each returns, because that return type is where most errors come from. (Searches for “map of r”, “r map” and “r-map” usually mean this function family; drawing geographic maps is a different task and is not covered here.)

What it is used for in research

Analysis scripts constantly repeat one step across many items: fit the same model to each of several datasets, read every file in a folder, summarise each column, or pull one field out of each record in a list of results. The purrr reference describes the map functions as transforming “their input by applying a function to each element of a list or atomic vector.” Writing that step once and mapping it over the items replaces a hand-written for loop and keeps the repeated operation in one place, which fits the habits behind computational reproducibility. If you are still working with loops, see for loops and the apply family in R first.

Install or access (official source only)

Map() ships with base R and needs nothing extra; it is documented in the base manual’s functional programming page (?Map). map() and its variants belong to the purrr package, whose reference and articles are published at purrr.tidyverse.org. Load it in a session with:

library(purrr)

Run your code in RStudio or any other R console.

Step-by-step: apply a function to every element

The usage on the current purrr reference page is map(.x, .f, ..., .progress = FALSE). .x is “a list or atomic vector” and .f is the function to apply.

Put your items in a list or vector. For example x <- list(a = 1:5, b = c(2, 4, 6), c = 10:12).
Write the function for one item. A named function such as mean works, as does an anonymous function written \(x) x + 1, the form the reference page shows.
Map it. map(x, mean) returns a list with one mean per element, keeping the names a, b, c.
Ask for a vector when each result is a single number. map_dbl(x, mean) returns a numeric vector instead of a list. The same signature exists for map_lgl(), map_int() and map_chr().
Pass fixed extra arguments with an anonymous function. The purrr page recommends map(x, \(v) mean(v, na.rm = TRUE)) over passing extra arguments through ....
Use walk() when you only want side effects, such as writing files or printing. Per the reference, “walk() returns the input .x (invisibly).”
Extract by name or position with a shorthand. A string or integer in place of a function works as shorthand for pluck(): map(results, "estimate") pulls the element called estimate from each item, and map(results, 3) pulls the third. The .default argument supplies a value when the element is NULL or missing, for example map(results, 3, .default = NA).

Base R’s Map() over several vectors

The base manual says Map(f, ...) “applies a function to the corresponding elements of given vectors”, and that it is “a simple wrapper to mapply which does not attempt to simplify the result.” Example: Map(function(a, b) a + b, 1:3, 4:6) returns a list of three results. The purrr comparison article notes that “Map() has no way to supply additional constant arguments”; purrr’s map2() handles two vectors and pmap() handles more than two.

Progress bars and parallel runs

The .progress argument controls “whether to show a progress bar.” The reference also documents an in_parallel() wrapper that runs .f in parallel, which the page marks as experimental; in that case ... is not permitted.

Output and how to read it

The key to reading map output is knowing the return type before you run the code. The table below is taken from the purrr reference page.

Function	Returns	What .f must return
`map()`	A list	Anything
`map_lgl()`, `map_int()`, `map_dbl()`, `map_chr()`	An atomic vector of that type	A length-1 compatible vector
`map_vec()`	An atomic or S3 vector (set the type with `.ptype`)	Length-1 results of a consistent type
`walk()`	The input `.x`, invisibly	Anything; used for side effects

The purrr article on base R states that “all map functions are type stable: you can predict the type of the output using little information about the inputs.” A list printed with [[1]], [[2]] headers, or with your element names, is normal output from map().

Troubleshooting

I got a list when I wanted a vector

map() always returns a list. Switch to the typed variant that matches your result: map_dbl() for numbers, map_chr() for text, map_lgl() for TRUE/FALSE.

map_dbl() or map_chr() throws an error about length or type

The typed variants require .f to return a length-1 compatible vector for every element. If your function sometimes returns two values, NULL or a different type, use map() and inspect the list, or reshape the function so it returns one value.

Which element failed?

The reference states that “any errors thrown by .f will be wrapped in an error with class purrr_error_indexed”, so the error reports the position of the failing element instead of leaving you to bisect a long input.

A constant argument is not being passed

Use an anonymous function, map(x, \(v) f(v, k)), as the reference recommends. Base Map() cannot take constant arguments; switch to purrr’s map2() or pmap() with an anonymous function.

The old ~ .x formula is flagged

The formula form (map(x, ~ .x + 1)) is marked “No longer recommended” on the current reference page. Rewrite it as map(x, \(x) x + 1).

sapply() gave a different type than I expected

The purrr article observes that “the base functions sapply() and mapply() automatically simplify making the return value hard to predict”, and that sapply() on an empty list returns a list instead of a numeric vector. vapply() is type stable but verbose; the typed map_*() functions give the same guarantee more compactly.

Free alternatives (table)

Base R covers the same ground. The mapping below follows the purrr article “purrr <-> base R” and the base manual pages for lapply and Map.

Task	purrr	Base R	Note from the documentation
Apply to each element, return a list	`map()`	`lapply()`	lapply returns “a list of the same length as X”
Return a typed vector	`map_lgl()`, `map_int()`, `map_dbl()`, `map_chr()`; `map_vec()` for other types	`vapply()`	vapply has a pre-specified return type, “so it can be safer”
Simplify automatically	use the typed `map_*()` variants	`sapply()`	sapply is a wrapper of lapply returning a vector, matrix or array “if appropriate”
Two vectors in parallel	`map2()`	`Map()`, `mapply()`	Map is a wrapper to mapply that does not simplify
More than two vectors	`pmap()`	`Map()`, `mapply()`	Map takes the vectors to which the function is mapped
Loop for side effects	`walk()`	`for` loop	walk returns its input invisibly

FAQ

What does map do in R?

It applies a function to each element of a list or vector and collects the results. In purrr, map() returns a list; in base R, Map() applies a function across the corresponding elements of several vectors without simplifying the result.

What is the difference between map() and lapply()?

Both return a list with one entry per input element. purrr adds typed variants, the string and integer extraction shorthands, a .progress option and indexed errors; lapply is in base R and needs no package.

What is the difference between map() and Map()?

map() (purrr) works over one list or vector. Map() (base R) works over the corresponding elements of several vectors, and cannot take constant extra arguments. For two or more inputs, purrr’s equivalents are map2() and pmap().

What do “map of r”, “r map” and “r-map” mean?

These phrasings most often refer to the map functions above. Plotting geographic maps in R is a separate topic; for drawing charts with ggplot2 see ggplots in R.