Meaning of tilde and dot notation in dplyr

Question

Summary I was reading an article on the subject of dplyr's across function. Looking at the first example of use, I saw the use of operators that I have never seen before. I do not know if they are inherently apart of dplyr or from some other package. Either way, I do not understand their use in the code.

Code Example:

starwars |>
    summarize(across(where(is.character), ~ length(unique(.x))))

The result is a 1 x 8 tibble.

I understand the first argument to across, it is the second argument that perplexes me. What does ~length(unique(.x)) mean? What does the .x code mean? I understand that length is being applied to every character vector in the tibble, but what does "unique" do for the code fragment?

What have I tried to resolve this problem myself? I have tried using Google to search for [R] ~ operator and received no relevant results. I also tried rdrr.io, r-project.org, and CRAN without a resolution. As well as the tidyverse.org and the documentation for purrr--this was due to seeing someone reference purrr when using the very same syntax in their code.

Question:

Can someone help me understand what is happening internally?

Answer 1

This is called purr-style lambda, starting with a tilde ~ and using .x to refer to every individual column that has been selected in .cols argument. So:

# We can either use
starwars |> summarize(across(where(is.character), ~ length(unique(.x)))) 

# Or we can define our anonymous function like this
starwars |> summarize(across(where(is.character), function(x) length(unique(x)))) 

They are equivalent. But it should be noted that you specified your function to be applied on every column in starwars data set which is of class character. For this purpose in this code it uses where function which is a helper that applies a function (here is.character) to select only those columns that are of class character. Then we apply our anonymous function on each of them and saving the result in a separate column. So .x here represents every column of class character. Just note that |> is R's newly-created, native pipe operator.

We normally use %>% with tidyverse packages, but both are doing the same job of replacing the result of its LHS to the first argument of its RHS which is normally (and in this case) .data argument. One more thing to mention here, though it was used for another purpose below. In order to understand how lambda-style-formula is interpreted in the back end we can use as_mapper which is the powerhouse behind the varied function specifications that most purrr functions allow:

library(purrr)

> as_mapper(~ length(unique(.x)))
<lambda>
function (..., .x = ..1, .y = ..2, . = ..1) 
length(unique(.x))
attr(,"class")
[1] "rlang_lambda_function" "function" 

If you pay attention to its output, you will realize it is interpreted as an anonymous function we usually use.

For more info please read this documentation.

Answer 2

~ is a shortcut for writing lambda functions in the tidyverse. ~length(unique(.x)) will yield the same result as function(.x) {length(unique(.x))}.

This way of writing a function is most likely used with purrr library, in fact, purrr::as_mapper() recognizes this syntax and returns a function that can be called as any other in R.

For example: function f will tell me how many unique values does .x have. .x can also be referred to as . or ..1. If you have two arguments then .x and .y. And finally with n arguments ..1, ..2, ..3 .... ..n

require(purrr)
#> Loading required package: purrr

f <- as_mapper(~length(unique(.x)))

f2 <- as_mapper(~length(unique(.)))

f3 <- as_mapper(~length(unique(..1)))
  
f(mtcars$mpg) 
#> [1] 25
f2(mtcars$mpg)
#> [1] 25
f3(mtcars$mpg)
#> [1] 25

^{Created on 2021-07-05 by the reprex package (v2.0.0)}

Another example:

library(dplyr)
library(purrr)

#in all starwars columns that are character vectors, how many unique values are they?

starwars |>
  summarize(across(where(is.character), ~ length(unique(.x))))
#> # A tibble: 1 x 8
#>    name hair_color skin_color eye_color   sex gender homeworld species
#>   <int>      <int>      <int>     <int> <int>  <int>     <int>   <int>
#> 1    87         13         31        15     5      3        49      38

f <- as_mapper(~ if (is.character(.x)) length(unique(.x)) else NULL)

f_base <- function(.x) {if (is.character(.x)) length(unique(.x)) else NULL}

starwars %>% 
  map_dfc(f)
#> # A tibble: 1 x 8
#>    name hair_color skin_color eye_color   sex gender homeworld species
#>   <int>      <int>      <int>     <int> <int>  <int>     <int>   <int>
#> 1    87         13         31        15     5      3        49      38

starwars %>% 
  map_dfc(f_base)
#> # A tibble: 1 x 8
#>    name hair_color skin_color eye_color   sex gender homeworld species
#>   <int>      <int>      <int>     <int> <int>  <int>     <int>   <int>
#> 1    87         13         31        15     5      3        49      38

^{Created on 2021-07-05 by the reprex package (v2.0.0)}