Label dictionary

[teunbrand]

This PR aims to fix #5178.

Briefly, it adds labs(dict) that allows one to use a data-dictionary to label a plot based on variable names (rather than aesthetics).

Let's just jump into examples.
The premise of this idea is that somewhere in your analysis code, you have some nice labels about what variables in your dataset mean. For example, we could have the following for the mpg dataset.

devtools::load_all("~/packages/ggplot2")
#> ℹ Loading ggplot2

dict <- c(
  displ = "Engine Displacement",
  hwy   = "Highway miles per gallon",
  cty   = "City miles per gallon",
  drv   = "Drive train",
  manufacturer = "Manufacturer name",
  model = "Model name",
  year  = "Year of manufacture",
  cyl   = "Number of cylinders",
  trans = "Type of transmission",
  fl    = "Fuel type",
  class = "Type of car"
)

This PR lets you slap on such a dictionary to your labels, and all variable names will be translated. The benefit is that you only have to think about pretty lables for variables once and you needn't worry about them again.

ggplot(mpg, aes(class, cty, fill = drv)) +
  geom_boxplot() +
  labs(dict = dict)

Noteably, this doesn't work when having more complex expressions, like factor(cyl) instead of cyl. In such case, you can fall back to labelling the aesthetic, or you can add an entry like labs(dict = c(dict, factor(cyl) = dict[["cyl"]])). Also we can reuse the dictionary here because we're using the same dataset even though we're making a totally different plot.

ggplot(mpg, aes(displ, hwy, colour = factor(cyl))) +
  geom_point() +
  labs(dict = dict, colour = dict["cyl"])

^{Created on 2024-09-04 with reprex v2.1.1}

[larmarange]

This is a nice idea. Would it be better to have a more explicit argument, i.e. dictionary instead of dict?

[teunbrand]

I don't have too strong of an opinion on this, but I like that both labs() is terse and dict is terse.
Perhaps Thomas can render a decision on this one

[teunbrand]

Double check: do we overwrite labs if their value is already inside?
EDIT: No, we don't :)
TODO: rename to dictionary

devtools::load_all("~/packages/ggplot2/")
#> ℹ Loading ggplot2

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  labs(
    x = "foo",
    dictionary = c(foo = "foobar", hwy = "baz")
  )

^{Created on 2024-09-10 with reprex v2.1.1}

[shannonpileggi]

I love this idea! Thank you for initiating this work!

Just curious - have you given thought to workflows where the user doesn't actually specify a dictionary? For example, what if the data already has labels embedded, and the user wants those embedded labels to be displayed automatically? This would be a similar approach to the {gt} package.

library(gt)

# unlabelled data frame
df1 <- data.frame(x = 1)
gt(df1)

x
1

# labelled data frame
df2 <- df1
attr(df2$x, "label") <- "variable x description"
gt(df2)

variable x description
1

^{Created on 2024-10-25 with reprex v2.1.1}

[teunbrand]

Hi Shannon! We implemented something akin to what you describe in #5879 which is already merged in the dev version. You can give the dev version a spin if you like (and provide feedback if we can improve 😅 )

[shannonpileggi]

Ohhhhh thank you for pointing that out! Will take a look!

[thomasp85]

LGTM

[thomasp85]

This is being called on all labels, right? So if a user has given a label name that just happens to be in the dictionary it will get translated

To me it should only apply to fallback labels, but I'm open to hearing against this

[thomasp85]

Can't roll back my approval but let's talk this one out before merging :-)

[teunbrand]

It applies to all 'derived' labels, not labels that users give verbatim.
Is this the kind of situation you mean?

devtools::load_all("~/packages/ggplot2/")
#> ℹ Loading ggplot2

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  labs(
    x = "Engine Displacement",
    dictionary = c(displ = "NO NOT THIS ONE", hwy = "new label")
  )

^{Created on 2024-12-02 with reprex v2.1.1}

[teunbrand]

Also labs(x = "foo", dictionary = c(foo = "bar")) will give "foo" as label for x.

[thomasp85]

it was that last situation I was concerned about. As long as any explicitly given label is honoured I'm happy