position_jitternudge {ggpp}

Combined positions jitter and nudge

Description

position_jitternudge() combines into one function the action of position_jitter and 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 = c("as.is", "alternate", "split"),
  nudge.from = c("original", "original.x", "original.y", "jittered", "jittered.y",
    "jittered.x"),
  kept.origin = c("jittered", "original", "none")
)

position_jitter_keep(
  width = NULL,
  height = NULL,
  seed = NA,
  kept.origin = "original"
)

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, with nudge values in data rows order.

direction

One of "as.is", "alternate", "split", "split.x" or "split.y". A value of "none" replicates the behavior of position_nudge. "split" changes the sign of the nudge depending on the direction of the random jitter applied to each individual 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".

Details

Jitter with position_jitternudge() is identical to that with position_jitter while nudging is enhanced compared to 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 points 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 to 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 calls the same code imported 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" to override the default origin = "jittered".

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. With nudge.from = "original" the original values with no jitter and no nudge applied are returned as x_orig and y_orig.

Note

When direction = "split" is used together with no jitter, the split to left and right, or up and down is done at random.

Author(s)

Michał Krassowski, edited by Pedro J. Aphalo.

Source

https://github.com/slowkow/ggrepel/issues/161.

See Also

position_jitter, position_nudge, position_nudge_repel.

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

Examples

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

jitter_nudge <- position_jitternudge(width = 0.2, height = 2,
                                     seed = 123, x = 0.1,
                                     direction = "split",
                                     nudge.from = "jittered")
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.2, height = 2,
                                     seed = 123, x = 0.35,
                                     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 <- 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")))