position_nudge_line {ggpp}

Nudge labels away from a line

Description

position_nudge_line() is generally useful for adjusting the starting position of labels or text to be repelled while preserving the original position as the start of the segments. The difference compared to position_nudge_center is that the nudging is away from from a line or curve fitted to the data points or supplied as coefficients. While position_nudge_center() is most useful for "round-shaped", vertically- or horizontally elongated clouds of points, position_nudge_line() is most suitable when observations follow a linear or curvilinear relationship between x and y values. In contrast to position_nudge, position_nudge_line() returns in 'data' both the original coordinates and the nudged coordinates.

Usage

position_nudge_line(
  x = NA_real_,
  y = NA_real_,
  xy_relative = c(0.03, 0.03),
  abline = NULL,
  method = NULL,
  formula = y ~ x,
  direction = c("automatic", "none", "split"),
  line_nudge = 1,
  kept.origin = c("original", "none")
)

Arguments

x, y

Amount of vertical and horizontal distance to move. A numeric vector of length 1 or longer.

xy_relative

Nudge relative to x and y data expanse, ignored unless x and y are both NAs.

abline

a vector of length two giving the intercept and slope.

method

One of "spline", "lm" or "auto".

formula

A model formula for lm when method = "lm". Ignored otherwise.

direction

One of "automatic", "none", or "split".

line_nudge

A positive multiplier >= 1, increasing nudging away from the curve or line compared to nudging from points.

kept.origin

One of "original" or "none".

Details

The default amount of nudging is 3 x and y axes, which in most cases is good. In most cases it is best to apply nudging along a direction perpendicular to the line or curve, if this is the aim, passing an argument to only one of x, y or xy_relative will be enough. When direction = "split" nudging is away from an implicit line or curve on either side with positive nudging. The line or curve can be smooth spline or linear regression fitted on-the-fly to the data points, or a straight line defined by its coefficients passed to abline. The fitting is well defined only if the observations fall roughly on a curve or straight line that is monotonic in y. By means of line_nudge one can increment nudging away from the line or curve compared to away from the points, which is useful for example to keep labels outside of a confidence band. Direction defaults to "split" when line_nudge > 1, and otherwise to "none".

Value

A "Position" object.

Note

For method = "lm" only model formulas corresponding to polynomials with no missing terms are supported. If usingpoly in the model formula, raw = TRUE is required.

In practice, x and y should have the same sign for nudging to work correctly.

This position is most useful when labeling points conforming a cloud along an arbitrary curve or line.

See Also

position_nudge, position_nudge_repel.

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

Examples

set.seed(16532)
df <- data.frame(
  x = -10:10,
  y = (-10:10)^2,
  yy = (-10:10)^2 + rnorm(21, 0, 4),
  yyy = (-10:10) + rnorm(21, 0, 4),
  l = letters[1:21]
)

# Setting the nudging distance

ggplot(df, aes(x, y, label = l)) +
  geom_line(linetype = "dotted") +
  geom_point() +
  geom_text(position = position_nudge_line())

ggplot(df, aes(x, y, label = l)) +
  geom_line(linetype = "dotted") +
  geom_point() +
  geom_text_s(position = position_nudge_line())

ggplot(df, aes(x, y, label = l)) +
  geom_line(linetype = "dotted") +
  geom_point() +
  geom_text(position = position_nudge_line(xy_relative = -0.03))

ggplot(df, aes(x, y, label = l)) +
  geom_line(linetype = "dotted") +
  geom_point() +
  geom_text(position = position_nudge_line(x = 0.6, y = 3.2))

ggplot(df, aes(x, y, label = l)) +
  geom_line(linetype = "dotted") +
  geom_point() +
  geom_text(position = position_nudge_line(x = -0.6, y = -4))

# Other curves, using defaults

ggplot(df, aes(x, -y, label = l)) +
  geom_line(linetype = "dotted") +
  geom_point() +
  geom_text(position = position_nudge_line())

ggplot(subset(df, x >= 0), aes(y, sqrt(y), label = l)) +
  geom_line(linetype = "dotted") +
  geom_point() +
  geom_text(position = position_nudge_line())

# Points scattered near a curve or line, we use 'direction = "split"'

ggplot(df, aes(x)) +
  geom_line(aes(y = y), linetype = "dotted") +
  geom_point(aes(y = yy)) +
  geom_text(aes(y = yy, label = l),
            position = position_nudge_line(direction = "split"))

ggplot(subset(df, x >= 0), aes(y, yy)) +
  stat_smooth(method = "lm", formula = y ~ x) +
  geom_point() +
  geom_text(aes(label = l),
            position = position_nudge_line(direction = "split"))

# increasing the nudging for labels near the line

ggplot(subset(df, x >= 0), aes(y, yy)) +
  stat_smooth(method = "lm", formula = y ~ x) +
  geom_point() +
  geom_text(aes(label = l),
              position = position_nudge_line(line_nudge = 2,
                                             direction = "split"))

# fitting a linear model instead of the default spline

ggplot(subset(df, x >= 0), aes(y, yy)) +
  stat_smooth(method = "lm", formula = y ~ x) +
  geom_point() +
  geom_text(aes(label = l),
            position = position_nudge_line(method = "lm",
                                           direction = "split"))

ggplot(subset(df, x >= 0), aes(x, x^2)) +
  stat_smooth(method = "lm", formula = y ~ poly(x, 2, raw = TRUE)) +
  geom_point() +
  geom_text(aes(label = l),
            position = position_nudge_line(method = "lm",
                                           formula = y ~ poly(x, 2, raw = TRUE)))