ggpp (version 0.4.3)

position_jitternudge: Combined positions jitter and nudge

Description

`position_jitternudge()` combines into one function the action of [ggplot2::position_jitter] and [ggplot2::position_nudge]. It is useful when labels to jittered plots and when adding jitter to text labels linked to points plotted without jitter. It can replace other position functions as it is backwards compatible. Like all other position functions in 'ggpp' and 'ggrepel' it preserves the initial position to allow drawing of segments or arrow linking the original position to the displaced one.

Usage

position_jitternudge(
  width = NULL,
  height = NULL,
  seed = NA,
  x = 0,
  y = 0,
  direction = "as.is",
  nudge.from = "original",
  kept.origin = "jittered"
)
position_jitter_keep(width = NULL, height = NULL, seed = NA)

Arguments

width, height

Amount of vertical and horizontal jitter. The jitter is added in both positive and negative directions, so the total spread is twice the value specified here. If omitted, defaults to 40 resolution of the data: this means the jitter values will occupy 80 implied bins. Categorical data is aligned on the integers, so a width or height of 0.5 will spread the data so it's not possible to see the distinction between the categories.

seed

A random seed to make the jitter reproducible. Useful if you need to apply the same jitter twice, e.g., for a point and a corresponding label. The random seed is reset after jittering. If NA (the default value), the seed is initialised with a random value; this makes sure that two subsequent calls start with a different seed. Use NULL to use the current random seed and also avoid resetting (the behaviour of ggplot 2.2.1 and earlier).

x, y

Amount of vertical and horizontal distance to move. A numeric vector of length 1, or of the same length as rows there are in `data`,

direction

One of "as.is", "alternate", "split", "split.x" or "split.y". A value of "none" replicates the behavior of [ggplot2::position_nudge]. At the moment "split" changes the sign of the nudge depending on the direction of the random jitter applied to each indidual observation, which is suitable for nudging labels outward of the jittered data.

nudge.from

One of "original", "jittered", "original.y" (or "jittered.x"), "original.x" (or "jittered.y"). A value of "original" applies the nudge before jittering the observations, while "jittered" applies the nudging after jittering.

kept.origin

One of "original", "jittered" or "none".

Value

A "Position" object. The layer function within it returns a data frame, with the jittered + nudged values in columns `x` and `y` and by default the jittered values with no nudging as `x_orig` and `y_orig`. When passing `nudge.from = "original` the original values with no jitter or nudge applied are returned instead as `x_orig` and `y_orig`.

Details

Jitter is identical to that by [ggplot2::position_jitter] while nudging is enhanced compared to [ggplot2::position_nudge] by taking into use cases specific to the combination of jitter and nudge.

There are two posible uses for this function. First it can be used to label jittered point in a plot. In this case, it is mandatory to use the same arguments to `width`, `height` and `seed` when passing `position_jitter()` to `geom_point()` and `position_jitternudge()` to `geom_text()` or `geom_label()` or their repulsive equivalents. Otherwise the arrows or segments will fail to connect to the labels. In other words jittering is computed twice. Jitter should be identical with the same arguments as `position_jitternudge()` as this last function simply call the same code from package 'ggplot2'.

The second use is to jitter labels to be connected to points that have not been jittered. The return of original positions instead of the jittered ones is achieved by passing `origin = "original"` instead of the default of `origin = "jittered".`

See Also

[ggplot2::position_jitter()], [ggplot2::position_nudge()], [ggrepel::position_nudge_repel()].

Other position adjustments: position_dodgenudge(), position_nudge_center(), position_nudge_line(), position_nudge_to(), position_stacknudge()

Examples

# NOT RUN {
jitter <- position_jitter(width = 0.3, height = 2, seed = 123)

jitter_nudge <- position_jitternudge(width = 0.3, height = 2,
                                     seed = 123, x = 0.4,
                                     direction = "as.is",
                                     nudge.from = "original.x")
ggplot(mpg[1:20, ],
       aes(cyl, hwy, label = drv)) +
  geom_point(position = jitter) +
  geom_text_s(position = jitter_nudge)

jitter_nudge <- position_jitternudge(width = 0.3, height = 2,
                                     seed = 123, x = -0.4,
                                     direction = "as.is",
                                     nudge.from = "original.x")
ggplot(mpg[1:20, ],
       aes(cyl, hwy, label = drv)) +
  geom_point(position = jitter) +
  geom_text_s(position = jitter_nudge)

jitter <- position_jitter(width = 0, height = 2, seed = 123)

jitter_nudge <- position_jitternudge(width = 0, height = 2,
                                     seed = 123, x = 0.4,
                                     direction = "split",
                                     nudge.from = "original.x")
ggplot(mpg[1:20, ],
       aes(cyl, hwy, label = drv)) +
  geom_point(position = jitter) +
  geom_text_s(position = jitter_nudge)

jitter_nudge <- position_jitternudge(width = 0, height = 2,
                                     seed = 123, x = 0.4,
                                     direction = "alternate",
                                     nudge.from = "original.x")
ggplot(mpg[1:20, ],
       aes(cyl, hwy, label = drv)) +
  geom_point(position = jitter) +
  geom_text_s(position = jitter_nudge)

# No nudge, show how points have moved with jitter

ggplot(mpg[1:20, ],
       aes(cyl, hwy, label = drv)) +
  geom_point() +
  geom_point_s(position =
               position_jitter_keep(width = 0.3, height = 2, seed = 123),
               color = "red",
               arrow = grid::arrow(length = unit(0.4, "lines")))

# }