Programming with facets

[hadley]

Extracted from R4DS because we're trying to get down to a page limit. I think this would be good content for https://ggplot2.tidyverse.org/articles/ggplot2-in-packages.html

---

Faceting

Unfortunately, programming with faceting is a special challenge, because faceting was implemented before we understood what tidy evaluation was and how it should work.
So you have to learn a new syntax.
When programming with facets, instead of writing ~ x, you need to write vars(x) and instead of ~ x + y you need to write vars(x, y).
The only advantage of this syntax is that vars() uses tidy evaluation so you can embrace within it:

# https://twitter.com/sharoz/status/1574376332821204999
foo <- function(x) {
  ggplot(mtcars, aes(x = mpg, y = disp)) +
    geom_point() +
    facet_wrap(vars({{ x }}))
}

foo(cyl)

As with data frame functions, it can be useful to make your plotting functions tightly coupled to a specific dataset, or even a specific variable.
For example, the following function makes it particularly easy to interactively explore the conditional distribution of carat from the diamonds dataset.

#| fig.show: hide

# https://twitter.com/yutannihilat_en/status/1574387230025875457
density <- function(color, facets, binwidth = 0.1) {
  diamonds |> 
    ggplot(aes(x = carat, y = after_stat(density), color = {{ color }})) +
    geom_freqpoly(binwidth = binwidth) +
    facet_wrap(vars({{ facets }}))
}

density()
density(cut)
density(cut, clarity)

[clauswilke]

@hadley On this topic, what's the latest recommendation for faceting? ~variable or vars(variable)? Is this text meant to say that normally we use ~ but when we want to write functions using faceting we need to use vars()?

And, related, is there a way of setting up a facet grid of the form x ~ y with vars()? If yes, it might be worthwhile to add that to the text. And if not, also worthwhile to note.

All these are questions that routinely come up in my dataviz class.

[hadley]

@clauswilke I don't know 😭 I now think the correct syntax is probably facet_grid(rows = foo, cols = c(bar, baz)) but I don't see how we get there from where we are now.

[clauswilke]

Could we introduce functions with new names and a new interface, and keep the old functions around for backwards compatibility? The current names are pretty tight, unfortunately, but maybe somebody has a stroke of genius for new names. sm_wrap() and sm_grid() for small multiples wrap/grid might not be bad. I think overall in the dataviz world the term "small multiples" is more widely accepted than "facet".

Unfortunately it wouldn't help with with my online class with 30h of video recorded, but eventually I'll probably record a new set.

[teunbrand]

Please excuse my naivety, but what is the major hurdle for allowing rows = foo? I understand that cols = c(bar, baz) might be difficult because mutations are allowed in vars() or in a formula, and we therefore can't use tidyselect. However, cols = list(bar, baz) could be made workable, no?

With regards to the sm abbreviation: I think in some languages, my mother tongue included, that might evoke a NSFW topic.

[clauswilke]

@teunbrand Regarding the naming: multiples_wrap()?

[hadley]

IMO it would be very hard for me to move away from the facet_ prefix, and while the faceting term isn't super common, it's used everywhere in the ggplot2 docs. I'm not sure about facet_wrap(), but one alternative for facet_grid() could be facet_rect(). Or another idea would be facet_1d() and facet_2d().

@teunbrand the problem is that then we don't know if facet_grid(rows = var) means facet by the data-var "var" or facet by the data-vars stored in the env-var var. We have explored various ways to work around this in the past, but there's no 100% principled way to do it, and we've invariably ended up regretting it.