position_nudge_to: Nudge labels to new positions

In aphalo/ggpp: Grammar Extensions to 'ggplot2'

Nudge labels to new positions

Description

position_nudge_to() differs from position_nudge in that the coordinates of the new position are given directly, rather than as a displacement from the original location. It optionally sets an even spacing among positions within a range. As with other position functions in this package, the original positions are preserved to allow the text or labels to be linked back to their original position with a segment or arrow.

Usage

position_nudge_to(
  x = NULL,
  y = NULL,
  x.action = c("none", "spread"),
  y.action = c("none", "spread"),
  x.distance = "equal",
  y.distance = "equal",
  x.expansion = 0,
  y.expansion = 0,
  kept.origin = c("original", "none")
)

Arguments

x, y	Coordinates of the destination position. A vector of mode numeric, that is extended if needed, to the same length as rows there are in data. The default, NULL, leaves the original coordinates unchanged.
x.action, y.action	character string, one of "none", or "spread". With "spread" distributing the positions within the range of argument x or y, if non-null. Otherwise, using the range the variable mapped to x or y.
x.distance, y.distance	character or numeric Currently only "equal" is implemented, indicating equal spacing between the spread positions.
x.expansion, y.expansion	numeric vectors of length 1 or 2, as a fraction of width of the range used to spread positions.
kept.origin	One of "original" or "none".

Details

The nudged to x and/or y values replace the original ones in data, while the original coordinates are returned in x_orig and y_orig. Nudge values supported are those of mode numeric, thus including dates and times when they match the mapped data.

If the length of x and/or y is more than one but less than the rows present in the data, the vector is both recycled and reordered so that the nudges are applied sequentially based on the data values. If their length matches the number of rows in data, they are assumed to be already in data order.

Irrespective of the action, the ordering of rows in data is preserved.

Value

A "Position" object.

Note

The current implementation DOES NOT support flipping geoms with the orientation argument or implicitly by the mapping. It DOES NOT apply scale transformations when spreading the positions.

See Also

position_nudge, position_nudge_repel.

Other position adjustments: position_dodgenudge(), position_dodgenudge_to(), position_jitternudge(), position_nudge_center(), position_nudge_keep(), position_nudge_line(), position_stacknudge(), position_stacknudge_to()

Examples

# The examples below exemplify the features of position_nudge_to().
# Please see the vignette for examples of use cases.

df <- data.frame(
  x = c(1,3,2,5,4,2.5),
  y = c(2, 3, 2.5, 1.8, 2.8, 1.5),
  grp = c("A", "A", "A", "B", "B", "B"),
  grp.inner = c("a", "b", "c", "a", "b", "c"),
  label = c("abc","cd","d","c","bcd","a")
)

# default is no nudging
ggplot(df, aes(label, y, label = y)) +
  geom_col() +
  geom_text(position = position_nudge_to(),
            vjust = -0.2)

# a single y (or x) value nudges all observations to this data value
ggplot(df, aes(label, y, label = y)) +
  geom_col() +
  geom_label(position = position_nudge_to(y = 1))

ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text(position = position_nudge_to(y = 3.2))

ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_line() +
  geom_text(position = position_nudge_to(y = 0.1))

# with a suitable geom, segments or arrows can be added
ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text_s(position = position_nudge_to(y = 2.25))

# alternating in y value order because y has fewer values than rows in data
ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text_s(position = position_nudge_to(y = c(3, 0.1)))

# in data row order with as many nudge y values as rows in data
ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text_s(position = position_nudge_to(y = c(1.8, 2.3, 1.3, 2.8, 3, 0.1)))

# spread the values at equal distance within the available space
ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text_s(position =
                position_nudge_to(y = 4, x.action = "spread"))

ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text_s(position =
                position_nudge_to(y = 4, x.action = "spread")) +
scale_x_log10()

# spread the values at equal distance within the expanded available space
ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text_s(position =
                position_nudge_to(y = 4, x.action = "spread", x.expansion = 0.1))

# spread the values at equal distance within the range given by x
ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text_s(position =
                position_nudge_to(y = 4, x = c(1.5, 4), x.action = "spread"))

# currently if scale transformations are used, the x and/or y arguments must
# be transformed. WARNING: This will change in the near future!!

ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text_s(position =
                position_nudge_to(y = 4, x = log10(c(1.5, 4)), x.action = "spread")) +
scale_x_log10()

ggplot(df, aes(x, y, label = label)) +
  geom_point() +
  geom_text_s(position =
                position_nudge_to(y = log10(4), x.action = "spread")) +
scale_y_log10()

aphalo/ggpp documentation built on Feb. 27, 2025, 10:19 p.m.