Argument inconsistency between `case_when()` and `recode_values()`/`replace_values()`

[sonicseamus]

Hello, I am excited about the new dplyr verbs recode_values() and replace_values() and have been experimenting with working them into my code. However, when I was writing code, I noticed that I naturally wrote .default = as an argument for recode_values() and was surprised not to get an autocomplete. After checking the documentation, I realized that the .default, .ptype, and .unmatched arguments do not have period prefixes for these new verbs, even though they do for case_when().

I don't really care whether there's the prefix or not (I'm not up on my dplyr lore enough to know what qualifies an argument for having a . prefix), but can we have consistency in the arguments across these three verbs? This may well have been an intentional choice, in which case I'm curious what the rationale was! And am here to report that it was confusing, at least for this useR.

[OliveJy]

I made exactly the same remark after dplyr's announcement on r/stats.

I suspect the following point:

In replace_values, "default" is treated as a replacement value in the same way as the values in "to" and "from". This is not a control parameter, it is literally "the default value to be used". This is a data, not a meta-parameter.

But I find it very illegible and it increases the cognitive load when these new verbs should normally be used to simplify the writing of "case_when" which can be used whatever the situation.

[DavisVaughan]

This was intentional.

For context, in the tidyverse our intent is to only add the . prefix when the ... themselves can be named expressions. i.e. mutate() is a good example

mutate(.data, ...)

You can do df |> mutate(new_name = old_name + 1), where new_name is a name supplied in the .... We want to avoid any possible collision between column names you'd like to create and our argument names, like .data, hence we add the . to make it less likely to have a collision.

Due to a historical accident, case_when() was given dotted arguments like .default. The ... of case_when() are two sided formulas, but they are not intended to be named, i.e. this makes no sense:

case_when(my_name = col < 5 ~ "small")

So in reality it should have been case_when(..., default =) without the ..

---

When asking for feedback internally about replace_when(), recode_values(), and replace_values(), one major point of feedback from one of our college teachers was that teaching people about the . prefix was always a huge source of confusion. This led us to decide to move forward with giving the new functions non-dotted argument names, which is more in line with our "rule" about the .. We hoped it would be easier to teach.

I do recognize that on some level it can still make things confusing because case_when() is the outlier of the family "for historical reasons", and teachers would have to explain it as such.

On one hand we are a bit stuck with case_when(). It's been around for many years and lots of people use the .default argument at this point. However I did consider doing this for the 1.2.0 release:

case_when <- function(
  ...,
  default = NULL,
  unmatched = "default",
  ptype = NULL,
  size = NULL,
  .default = deprecated(),
  .ptype = deprecated(),
  .size = deprecated()
)

That makes the help page for case_when() very ugly to look at, but at least you can switch between any of the family of 4 and consistently not use the . version of the argument names.

I think over time we could get rid of .ptype and .size, but it would be extremely hard to get rid of .default entirely due to the sheer number of people who probably use it, so over time we might be able to get this down to

case_when <- function(
  ...,
  default = NULL,
  unmatched = "default",
  ptype = NULL,
  size = NULL,
  .default = deprecated()
)

In the end we decided that this amount of extra pain wasn't worth it. Especially in the short to medium term where case_when() looks like it has a ton of arguments.

I suppose it would immediately make the family of 4 easier to teach to newcomers though, because teachers would just leave out the deprecated arguments and all 4 would have a consistent non-dotted interface.

I'm not sure what we'll do here yet, but I recognize the issue and we'll talk it over some internally