% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/position-nudge-center.R
\name{position_nudge_center}
\alias{position_nudge_center}
\alias{position_nudge_centre}
\title{Nudge labels away from a central point}
\usage{
position_nudge_center(
  x = 0,
  y = 0,
  center_x = NULL,
  center_y = NULL,
  direction = NULL,
  obey_grouping = NULL,
  kept.origin = c("original", "none")
)

position_nudge_centre(
  x = 0,
  y = 0,
  center_x = NULL,
  center_y = NULL,
  direction = NULL,
  obey_grouping = NULL,
  kept.origin = c("original", "none")
)
}
\arguments{
\item{x, y}{Amount of vertical and horizontal distance to move. A numeric
vector, that is recycled if shorter than the number of rows in \code{data}.}

\item{center_x, center_y}{The coordinates of the virtual origin out from which
nudging radiates or splits in opposite directions. A numeric vector of
length 1 or of the same length as rows there are in \code{data}, or a
function returning either of these vectors computed from the variables in
data mapped to \code{x} or \code{y}, respectively.}

\item{direction}{One of \code{"none"}, \code{"radial"}, or \code{"split"}. A
value of \code{"none"} replicates the behavior of
\code{\link[ggplot2]{position_nudge}}. Which of these three values is the
default depends on the values passed to the other parameters.}

\item{obey_grouping}{A logical flag indicating whether to obey or not
groupings of the observations. By default, grouping is obeyed when both of
the variables mapped to \emph{x} and \emph{y} are continuous numeric and
ignored otherwise.}

\item{kept.origin}{One of \code{"original"} or \code{"none"}.}
}
\value{
A \code{"Position"} object.
}
\description{
\code{position_nudge_center()} is generally useful for adjusting the position of
labels or text, both on a discrete or continuous scale. In contrast to
\code{\link[ggplot2]{position_nudge}}, \code{position_nudge_center()} returns in \code{data} both
the original coordinates and the nudged coordinates.
}
\details{
This position function is backwards compatible with \code{\link[ggplot2]{position_nudge}}
but extends it by adding support for nudging that varies across the plotting
region, either in opposite directions or radially from a virtual \emph{center
point}.

Positive values as arguments to \code{x} and \code{y} are added to
  the original position along either axis. If no arguments are passed to
  \code{center_x}, \code{center_y} or \code{direction}, the nudging is
  applied as is, as is the case if \code{direction = "none"}. If
  non-\code{NULL} arguments are passed to both \code{center_x} and
  \code{center_y}, \code{direction = "radial"} is assumed. In this case, if
  \code{x} and/or \code{y} positive nudging is applied radially outwards from
  the center, while if negative, inwards towards the center. When a
  non-\code{NULL} argument is passed only to one of \code{center_x} or
  \code{center_y}, \code{direction = "split"} is assumed. In this case when
  the initial location of the point is to the left of \code{center_x},
  \code{-x} is used instead of \code{x} for nudging, and when the initial
  location of the point is to the below of \code{center_y}, \code{-y} is used
  instead of \code{y} for nudging. If non-\code{NULL} arguments are passed to
  both \code{center_x} and \code{center_y}, and \code{direction} is passed
  \code{"split"} as argument, then the split as described above is applied to
  both to \emph{x} and \emph{y} coordinates.
}
\note{
Some situations are handled as special cases. When \code{direction =
  "split"} or \code{direction = "radial"}, observations at exactly the _center_
  are nudged using \code{x} and \code{y} unchanged. When\code{direction = "split"},
  and
  both \code{center_x} and \code{center_y} have been supplied, segments are drawn at
  eight different possible angles. When segments are exactly horizontal or
  vertical they would be shorter than when drawn at the other four angles, in
  which case \code{x} or \code{y} are adjusted to ensure these segments are of the same
  lengths as those at other angles.

  This position is most useful when labelling points forming a cloud or
  grouped along vertical or horizontal lines or "divides".
}
\examples{
df <- data.frame(
  x = c(1,3,2,5,4,2.5),
  y = c("abc","cd","d","c","bcd","a")
)

# Plain nudging, same as with ggplot2::position_nudge()

ggplot(df, aes(x, y, label = y)) +
  geom_point() +
  geom_text_s(hjust = "left", vjust = "bottom",
              position = position_nudge(x = 0.2, y = 0.2))

ggplot(df, aes(x, y, label = y)) +
  geom_point() +
  geom_text_s(add.segments = FALSE,
              position = position_nudge_center(x = 0.2, y = 0.2)
  )

# "split" nudging

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_s(aes(label = y),
              add.segments = FALSE,
              position = position_nudge_center(x = 0.2,
                                               y = 0.2,
                                               direction = "split"))

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_s(aes(label = y),
              position = position_nudge_center(x = 0.4,
                                               direction = "split"))

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_s(aes(label = y),
              position = position_nudge_center(y = 0.2,
                                               direction = "split"))

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_s(aes(label = y),
              position = position_nudge_center(x = 0.2,
                                               y = 0.3,
                                               center_y = 2,
                                               center_x = 1.5,
                                               direction = "split"))

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_s(aes(label = y),
              position = position_nudge_center(x = 0.06,
                                               y = 0.08,
                                               center_y = 2))

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_s(aes(label = y),
              position = position_nudge_center(x = 0.1,
                                               center_x = 2.51))

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_s(aes(label = y),
              position = position_nudge_center(x = 0.06,
                                               y = 0.08,
                                               center_x = median,
                                               center_y = median,
                                               direction = "split"))

# "Radial" nudging

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_s(aes(label = y),
              position = position_nudge_center(x = 0.1,
                                               y = 0.2,
                                               direction = "radial"))

ggplot(df, aes(x, y)) +
  geom_point() +
  geom_text_s(aes(label = y),
              position = position_nudge_center(x = -0.1,
                                               y = -0.1,
                                               direction = "radial"))

df <- data.frame(
  x = -10:10,
  z = (-10:10)^2,
  y = letters[1:21],
  group = rep(c("a", "b"), rep(c(11, 10)))
)

ggplot(df, aes(x, z)) +
  geom_point() +
  geom_line() +
  geom_text_s(aes(label = y),
              position = position_nudge_center(x = 0.9,
                                               y = 2.7,
                                               center_x = mean,
                                               center_y = max))

ggplot(df, aes(x, z, color = group)) +
  geom_point() +
  geom_line(color = "black", linetype = "dotted") +
  geom_text_s(aes(label = y),
              position = position_nudge_center(x = -1.2,
                                               y = -3,
                                               center_x = 0,
                                               center_y = "above_max"))

ggplot(df, aes(x, z, color = group)) +
  geom_point() +
  geom_line(color = "black", linetype = "dotted") +
  geom_text(aes(label = y),
            vjust = "inward", hjust = "inward",
            position = position_nudge_center(x = -0.9,
                                             y = -2.7,
                                             center_x = mean,
                                             center_y = max,
                                             obey_grouping = FALSE))

}
\seealso{
[ggplot2::position_nudge()], [ggrepel::position_nudge_repel()].

Other position adjustments:
\code{\link[=position_dodgenudge]{position_dodgenudge()}},
\code{\link[=position_dodgenudge_to]{position_dodgenudge_to()}},
\code{\link[=position_jitternudge]{position_jitternudge()}},
\code{\link[=position_nudge_keep]{position_nudge_keep()}},
\code{\link[=position_nudge_line]{position_nudge_line()}},
\code{\link[=position_nudge_to]{position_nudge_to()}},
\code{\link[=position_stacknudge]{position_stacknudge()}},
\code{\link[=position_stacknudge_to]{position_stacknudge_to()}}
}
\concept{position adjustments}
