Review supersession

[teunbrand]

It'd be helpful to review which functions have preferred alternatives and mark them as superseded.
As an example, coord_polar() can be replaced with coord_radial(), but isn't documented like that.
I'd expect some helper functions to be functionally superseded as well.

[teunbrand]

Let's create a list. It's open for additional suggestions.

Already superseded:

• coord_flip() by inverting x/y aesthetics.
• annotation_logticks() by guide_axis_logticks().
• coord_map() and coord_quickmap() by coord_sf()

Considered for supersession:

• coord_polar() to be superseded by coord_radial()
• coord_equal() to be superseded by coord_fixed()
  • Perhaps these could even be incorporated in coord_cartesian(), they are easy to implement.
• expand_limits() should just be function to be passed to scale limits, e.g. limits = ~ range(.x, value).

[teunbrand]

Behaviour to supersede:

• options("ggplot2.continuous.colour"): use lifecycle signal superseded. Put superseded badges in documentation. Review documentation and books.

• supersede plot_env or soft-deprecate. Disentangle facet evaluation wrt plot_env. There is a related issue Drop plot_env from ggplot2 objects? #3994.

TODO: review arguments specifically.

[davidhodge931]

Could expand_limits not be superseded, please? I know you can do it in the scale via the limits argument with a function, but that is quite complex for a lot of users. It is a common need (e.g. adding a zero), so it's great to have a quick, easy method to do this

[teunbrand]

The problem with expand_limits() is that it is an extragrammatical way for implicitly settings the limits. The term 'limits' would also suggest this works at the scale level, but instead it adds a blank layer. It is hack that might be easy to use, but I'd suggest you're doing users a favour in the long term by instructing on the proper way to manipulate limits.

[davidhodge931]

Also, the new approach to setting colour palettes does not do entirely what the old options approach does, as you cannot set the NA value with the new approach.

Great to start the process of getting rid of the redundant functions!

[davidhodge931]

Not everyone needs to learn ggplot2 to an advanced level, @teunbrand

[clauswilke]

Not everyone needs to learn ggplot2 to an advanced level, @teunbrand

I think discoverability and ability to memorize patterns are both very important for regular users. I don't even know what limits = ~ range(.x, value) does.

In general, I have found that while it's great that there are all these nifty tricks that people can in principle use to get advanced outputs in an elegant way, in practice very few people have the mental capacity to memorize all these tricks and use them in the appropriate circumstances.

Not sure how useful this is in the present context, just pointing this out as something to keep in mind.

[teunbrand]

Separate from this PR, my idea is that there will be limit helper functions in scales, e.g. r-lib/scales#490. Which has the benefits of not being circuitous and being discoverable.

[clauswilke]

I was debating whether I should bring up the scales package as an example of a repository of great helper functions that can in principle solve all sorts of issues I have and that I can never remember how to use... ;-)

[davidhodge931]

Oh, those new scales helpers are really nice! +1 for UK spelling limits_centre ;)

While you're looking at supercession ideas, I just remembered this interesting post from a year ago on mastodon re xlim/ylim (& lims by association)
https://mastodon.social/@coolbutuseless@fosstodon.org/112602236033828285

[clauswilke]

@davidhodge931 We're completely off-topic now, but xlim() and ylim() should be replaced with functions that can modify the existing scale rather than adding a new scale. This is something we've talked about for a long time (#4269). We should be able to change scale properties such as limits, breaks, expansion, etc. without having to replace the existing scale. We just haven't come up with an implementation that is satisfactory.