11

I searched for ??"~" but this only points me to rlang::env_bind (presumably, %<~%) and base::~. Within RStudio, how can I find Purrr's ~'s documentation? For example, if I forgot how to use ~ with two inputs, where do I look?

J. Mini
  • 1,868
  • 1
  • 9
  • 38
  • 2
    The tilde operator is not specific for `purrr`, it's part of the language. See the language definition: https://cran.r-project.org/doc/manuals/r-release/R-lang.html – tmfmnk May 21 '21 at 19:51
  • 2
    @tmfmnk "_~ Tilde, used for model formulae, can be either unary or binary_". Nothing about that suggests anonymous functions. – J. Mini May 21 '21 at 19:56
  • 2
    This question/answer might be useful to understanding the ~ (but doesn't point to documentation): https://stackoverflow.com/questions/44834446/what-is-meaning-of-first-tilde-in-purrrmap – aosmith May 21 '21 at 19:58
  • 2
    Yes, and it is stated in the documentation of the `map()` functions that the `.f` parameter is `a function, formula, or vector (not necessarily atomic).`. – tmfmnk May 21 '21 at 19:59
  • @tmfmnk So there is nothing special about `~` within Purrr, it's just that Purrr's functions have a special way of reading base R's formula objects? And, for example, this is why base R's `Map` will not work when given formulae expressed in `~` form, even when Purrr is loaded and the same call (albeit with the arguments moved) would have worked for `purrr::map`? Great. That's an answer. Feel free to tidy that up and submit it. – J. Mini May 21 '21 at 20:01
  • I think that the use of tilde operator in `purrr::map()` is beautifully explained in the thread linked by @aosmith . Then, as far as I'm concerned, `base::Map()` does not accept a formula as its `f` parameter. – tmfmnk May 21 '21 at 20:06
  • @J.Mini, in response to your *"nothing about that suggests anonymous functions"*, I'll say that nothing in your question suggests anon-funcs, either. Yes, some functions in `purrr` allow special use of the `~` as a fake function, but then again, I believe they do nothing special but use its constructs as already provided by R. Most base-R functions do not support this, it's primarily (solely?) with tidyverse packages. – r2evans May 21 '21 at 20:09
  • 2
    If you forget how to use `~` with two inputs, then you need to look at the function that is allowing the `~`-function, not `~` itself. For instance, `purrr::pmap` shows three ways to parameterize it, using `.` (single argument), `.x` and `.y` (if only two), or `..1`, `..2`, `..3`, etc for multi-arg `~`-functions. – r2evans May 21 '21 at 20:11
  • @r2evans Completely fair and correct points, but for what it's worth, I don't think that the documentation for `pmap` shows how to use the `..n` variants. – J. Mini May 21 '21 at 20:47
  • Huh? `?pmap`: `.f: A function, formula, or vector ... - For more arguments, use '..1', '..2', '..3' etc`. Perhaps there's a version discrepancy? (Or I'm just missing something else ...) – r2evans May 21 '21 at 20:57
  • @r2evans I was specifically referring to there being no such examples in the example code. – J. Mini May 22 '21 at 17:42

2 Answers2

5

There is a good explanation given AdvanceR (link given in another answer). There is also a short description (usage example) given in purrr cheatsheat first page bottom left.

enter image description here

The usage of multiple arguments with twiddle ~ may be seen at with documentation of purrr given in its different functions. e.g. map see argument description which states that

.f A function, formula, or vector (not necessarily atomic). If a function, it is used as is. If a formula, e.g. ~ .x + 2, it is converted to a function. There are three ways to refer to the arguments: For a single argument function, use .

For a two argument function, use .x and .y

For more arguments, use ..1, ..2, ..3 etc

This syntax allows you to create very compact anonymous functions.

Moreover, R in its newest version (4.1.0) has also started similar kind of shorthand notation of functions

R now provides a shorthand notation for creating functions, e.g. \(x) x + 1 is parsed as function(x) x + 1.

This shorthand notation may also provide useful in functions outside tidyverse, with only differentiation from twiddle being that here arguments are not named by default. But again, this non-default naming may also be proved useful when one invisible function is to be used inside another and twiddle style of notation will not work in that case.

AnilGoyal
  • 25,297
  • 4
  • 27
  • 45
  • `twiddle` is very different from the new base R anonymous function syntax. For example, `twiddle` does not actually make an anonymous function; purrr's functions merely coerce the formula object to what they can treat as a function. – J. Mini May 24 '21 at 17:19
  • @J.Mini, yes you're right and I am aware of this. May be I was unable to convey this properly. – AnilGoyal May 24 '21 at 17:22
4

When you use ~ within the context of purrr functions, it will be passed to the as_mapper() function, which in turn passes on to the as_function() function from rlang. These help files have a very basic bit of what is needed to use this. This is further documented in the Advanced R Book Chapter 9, Section 9.22, which has a few good examples, and this chapter goes on to continue those ideas.

Michael Barrowman
  • 953
  • 7
  • 14