The map functions transform their input by applying a function toeach element of a list or atomic vector and returning an object ofthe same length as the input.
map()always returns a list. See themodify()family forversions that return an object of the same type as the input.map_lgl(),map_int(),map_dbl()andmap_chr()return anatomic vector of the indicated type (or die trying). For these functions,.fmust return a length-1 vector of the appropriate type.map_vec()simplifies to the common type of the output. It works withmost types of simple vectors like Date, POSIXct, factors, etc.walk()calls.ffor its side-effect and returnsthe 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 + 1orfunction(x) x + 1.A formula, e.g.
~ .x + 1. You must use.xto refer to the firstargument. Only recommended if you require backward compatibility witholder versions of R.A string, integer, or list, e.g.
"idx",1, orlist("idx", 1)whichare shorthand for\(x) pluck(x, "idx"),\(x) pluck(x, 1), and\(x) pluck(x, "idx", 1)respectively. Optionally supply.defaulttoset a default value if the indexed element isNULLor 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 ofx |> map(f, 1, 2, collapse = ",")# do:x |> map(\(x) f(x, 1, 2, collapse = ","))This makes it easier to understand which arguments belong to whichfunction and will tend to yield better error messages.
- .progress
Whether to show a progress bar. Use
TRUEto turn ona basic progress bar, use a string to give it a name, or seeprogress_bars for more details.- .ptype
If
NULL, the default, the output type is the common typeof the elements of the result. Otherwise, supply a "prototype" givingthe 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 atomicvector of length 1._vec()return an atomic or S3 vector, the same type that.freturns..fcan return pretty much any type of vector, as long as its length 1.walk()returns the input.x(invisibly). This makes it easy touse in a pipe. The return value of.f()is ignored.
Any errors thrown by .f will be wrapped in an error with classpurrr_error_indexed.
See also
map_if() for applying a function to only those elementsof .x that meet a specified condition.
Other map variants: imap(),lmap(),map2(),map_depth(),map_if(),modify(),pmap()
Examples
# Compute normal distributions from an atomic vector1:10 |> map(rnorm, n = 10)#> [[1]]#> [1] 1.6215527 2.1484116 -0.8218177 0.7526747 0.7558004 0.7172946#> [7] 0.4463006 1.6289820 3.0650249 -0.6309894#> #> [[2]]#> [1] 2.5124269 0.1369885 1.4779875 1.9473981 2.5429963 1.0859252 2.4681544#> [8] 2.3629513 0.6954565 2.7377763#> #> [[3]]#> [1] 4.888505 2.902555 2.064153 2.984050 2.173211 1.487600 3.935363#> [8] 3.176489 3.243685 4.623549#> #> [[4]]#> [1] 4.112038 3.866003 2.089913 3.720763 3.686554 5.067308 4.070035#> [8] 3.360877 3.950035 3.748517#> #> [[5]]#> [1] 5.444797 7.755418 5.046531 5.577709 5.118195 3.088280 5.862086#> [8] 4.756763 4.793913 5.019178#> #> [[6]]#> [1] 6.029561 6.549828 3.725885 8.682557 5.638779 6.213356 7.074346#> [8] 5.334912 7.113952 5.754104#> #> [[7]]#> [1] 5.822437 6.024149 8.065057 7.131671 7.488629 5.300549 5.529264#> [8] 7.284150 8.337320 7.236696#> #> [[8]]#> [1] 9.318293 8.523910 8.606748 7.890064 8.172182 7.909673 9.924343#> [8] 9.298393 8.748791 8.556224#> #> [[9]]#> [1] 8.451743 10.110535 6.387666 8.844306 9.433890 8.618049 9.424188#> [8] 10.063102 10.048713 8.961897#> #> [[10]]#> [1] 10.486149 11.672883 9.645639 10.946348 11.316826 9.703360 9.612786#> [8] 9.214567 8.943263 9.204459#> # You can also use an anonymous function1:10 |> map(\(x) rnorm(10, x))#> [[1]]#> [1] -0.7562754 0.3094621 0.4414580 0.4633367 1.2271271 1.9784549#> [7] 0.7911173 -0.3994105 1.2585373 0.5582005#> #> [[2]]#> [1] 2.5685999 4.1268505 2.4248584 0.3157185 2.2494018 3.0728383 4.0393693#> [8] 2.4494538 3.3918140 2.4265665#> #> [[3]]#> [1] 3.107584 3.022295 3.603611 2.737349 2.471736 3.192149 1.853800#> [8] 3.846185 3.081720 1.694883#> #> [[4]]#> [1] 3.055088 4.454342 3.144797 3.713105 4.894962 4.067304 3.837324#> [8] 3.172690 5.876506 4.766440#> #> [[5]]#> [1] 5.979957 6.321781 3.880289 5.514600 3.490900 6.532741 5.429147#> [8] 5.122103 3.861988 4.441985#> #> [[6]]#> [1] 7.052539 6.677684 6.038500 5.643619 6.782844 6.804412 4.099939#> [8] 6.935784 5.690948 6.263067#> #> [[7]]#> [1] 5.209408 6.211741 5.866978 7.363653 6.714112 7.517669 6.897091#> [8] 6.025930 8.270672 7.960865#> #> [[8]]#> [1] 8.768721 9.035931 7.526113 6.724665 7.694379 10.211769 6.958332#> [8] 6.853476 6.324673 9.525939#> #> [[9]]#> [1] 9.554186 10.993110 8.845879 11.564408 10.061999 10.142695 10.123839#> [8] 8.602999 8.176739 8.421115#> #> [[10]]#> [1] 11.763789 10.132992 10.376499 11.138708 11.241263 10.612091 9.570620#> [8] 11.360461 9.929143 9.727846#> # Simplify output to a vector instead of a list by computing the mean of the distributions1:10 |> map(rnorm, n = 10) |> # output a list map_dbl(mean) # output an atomic vector#> [1] 0.449421 2.083007 2.739160 4.144721 4.716806 5.978606 6.593186#> [8] 8.619169 9.087989 10.312465# Using set_names() with character vectors is handy to keep track# of the original inputs:set_names(c("foo", "bar")) |> map_chr(paste0, ":suffix")#> foo bar #> "foo:suffix" "bar:suffix" # Working with listsfavorite_desserts <- list(Sophia = "banana bread", Eliott = "pancakes", Karina = "chocolate cake")favorite_desserts |> map_chr(\(food) paste(food, "rocks!"))#> Sophia Eliott Karina #> "banana bread rocks!" "pancakes rocks!" "chocolate cake rocks!" # Extract by name or position# .default specifies value for elements that are missing or NULLl1 <- list(list(a = 1L), list(a = NULL, b = 2L), list(b = 3L))l1 |> map("a", .default = "???")#> [[1]]#> [1] 1#> #> [[2]]#> [1] "???"#> #> [[3]]#> [1] "???"#> l1 |> map_int("b", .default = NA)#> [1] NA 2 3l1 |> map_int(2, .default = NA)#> [1] NA 2 NA# Supply multiple values to index deeply into a listl2 <- list( list(num = 1:3, letters[1:3]), list(num = 101:103, letters[4:6]), list())l2 |> map(c(2, 2))#> [[1]]#> [1] "b"#> #> [[2]]#> [1] "e"#> #> [[3]]#> NULL#> # 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 existl2 |> map(list("num", 3))#> [[1]]#> [1] 3#> #> [[2]]#> [1] 103#> #> [[3]]#> NULL#> l2 |> map_int(list("num", 3), .default = NA)#> [1] 3 103 NA# Working with data frames# Use map_lgl(), map_dbl(), etc to return a vector instead of a list:mtcars |> map_dbl(sum)#> mpg cyl disp hp drat wt qsec vs #> 642.900 198.000 7383.100 4694.000 115.090 102.952 571.160 14.000 #> am gear carb #> 13.000 118.000 90.000 # A more realistic example: split a data frame into pieces, fit a# model to each piece, summarise and extract R^2mtcars |> split(mtcars$cyl) |> map(\(df) lm(mpg ~ wt, data = df)) |> map(summary) |> map_dbl("r.squared")#> 4 6 8 #> 0.5086326 0.4645102 0.4229655 