Extracting guide data (version 3)

[teunbrand]

This PR aims to fix #5004 and replaces #5337.

Briefly, it defines the new guide_data() function to programatically access values and labels of axes and legends. More motivation is described in #5096.

Because guides are now build in ggplot_build(), we can extract the keys more cleanly than #5337. That this PR's footprint more focussed and minimal.

Examples (same as #5337):

devtools::load_all("~/packages/ggplot2/")
#> ℹ Loading ggplot2
#> Warning: package 'testthat' was built under R version 4.3.1

# A typical plot
p <- ggplot(mtcars) +
  aes(mpg, disp, colour = drat, size = drat) +
  geom_point() +
  facet_wrap(vars(cyl), scales = "free_x")

# Getting guide data for position aesthetic in particular panel
guide_data(p, "x", i = 1, j = 2)
#>           x .value .label y
#> 1 0.0959596     18     18 0
#> 2 0.3484848     19     19 0
#> 3 0.6010101     20     20 0
#> 4 0.8535354     21     21 0

# Getting guide data for a legend
guide_data(p, "size")
#>       size .value .label
#> 1 2.662822    3.0    3.0
#> 2 3.919819    3.5    3.5
#> 3 4.779645    4.0    4.0
#> 4 5.477285    4.5    4.5

# If guides are merged, `guide_data()` reports merged guide data
guide_data(p + guides(colour = "legend"), "size")
#>    colour .value .label     size
#> 1 #1A3855    3.0    3.0 2.662822
#> 2 #28557C    3.5    3.5 3.919819
#> 3 #3874A5    4.0    4.0 4.779645
#> 4 #4894D0    4.5    4.5 5.477285

^{Created on 2023-11-03 with reprex v2.0.2}

[teunbrand]

I've renamed the function to get_guide_data() to prevent the confusion that guide_data() might be a guide that can be fed to a scale or guides(): it is not.

[thomasp85]

How does this play with facets from extension packages that might not adhere to a strict grid of panels?

[teunbrand]

Depends on how the facets handle the layout I suppose. From my own package, facet_manual() has .LEFT, .RIGHT, .TOP and .BOTTOM instead of ROW and COL, so it won't work.

devtools::load_all("~/packages/ggplot2")
#> ℹ Loading ggplot2
library(ggh4x)
#> 
#> Attaching package: 'ggh4x'
#> 
#> The following object is masked from 'package:ggplot2':
#> 
#>     guide_axis_logticks

ggplot(mtcars, aes(mpg, wt)) +
  geom_point() +
  facet_manual(
    ~ cyl, design = matrix(c(1,1,NA,NA,NA,2,2,NA,NA,NA,3,3), nrow = 4)
  )

get_guide_data(last_plot(), aesthetic = "x", i = 1, j = 1)
#> NULL

^{Created on 2023-12-14 with reprex v2.0.2}

[thomasp85]

Maybe we should just allow a single index to not force a tabular layout. I know that would require some knowledge about how the facet lays out the panels but this is not something for the standard user anyway

[thomasp85]

basically use [[ indexing rather than [

[teunbrand]

I like that idea, and match PANEL instead of ROW/COL. I think PANEL should be used in most facet extensions, I'd think.

[teunbrand]

I'm assuming that Thomas' approval still holds after implementing his suggestions, so I'll go ahead and merge this in.