Document vector passing to nudge_y/nudge_x/position_nudge

[MaxAtoms]

Recently, when creating plots with ggstatsplot (using the ggbetweenstats function), I wanted to move the centrality labels for each distribution individually. It took me quite some time to figure out that I can pass a vector to nudge_y (or position_nudge for that matter).

Therefore, I propose to document this functionality.

[teunbrand]

Thank you for the PR! We generally don't want to encourage passing aesthetics outside aes() as vectors for the reasons documented in most layers like ?geom_point:

Please note that while passing unmapped aesthetics as vectors is technically possible, the order and required length is not guaranteed to be parallel to the input data.

If you want to pass it like aes(nudge_y = c(...)) that'd be fine with me. If you intend to change the example, would you mind running devtools::document() so that the changes propagate to the .Rd files?

[MaxAtoms]

Sorry, if I am ignorant here, but wrapping nudge_y in aes() gives me Ignoring unknown aesthetics: nudge_y.
Am I understanding something wrong here?

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text(aes(label = y, nudge_y = c(-0.1, 0.1, -0.1, 0.1)))

The same error happens when setting position = position_nudge withinaes().

[teunbrand]

The development version of ggplot2 understands nudge_x and nudge_y to be aesthetics of position_nudge(), which isn't on CRAN yet. One of the motivating reasons was exactly because we don't want to encourage vectorised input to parameters/aesthetic outside the aes() function.

# Load the development version on my personal machine
devtools::load_all("~/packages/ggplot2/")
#> ℹ Loading ggplot2

df <- data.frame(
  x = factor(c(1, 1, 2, 2)),
  y = c(1, 3, 2, 1),
  grp = c("a", "b", "a", "b")
)

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text(aes(label = y, nudge_y = c(-0.1, 0.1, -0.1, 0.1)))

^{Created on 2025-02-21 with reprex v2.1.1}

[MaxAtoms]

Ah, I see. So you might want to change the target branch of this PR to a development branch?

I added the change and ran devtools::document().
Please note that there also changes to hmisc.Rd.

[teunbrand]

This looks good to me: thank you very much for the contribution!

you might want to change the target branch of this PR to a development branch

The main branch is the development branch, the released versions are tagged.