position_jitternudge.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/position-nudge-jitter.R
\name{position_jitternudge}
\alias{position_jitternudge}
\alias{position_jitter_keep}
\title{Combined positions jitter and nudge}
\source{
\url{https://github.com/slowkow/ggrepel/issues/161}.
}
\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)
}
\arguments{
\item{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% of the
resolution of the data: this means the jitter values will occupy 80% of the
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.}

\item{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 \code{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 \code{NULL} to use
the current random seed and also avoid resetting (the behaviour of ggplot
2.2.1 and earlier).}

\item{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 \code{data},}

\item{direction}{One of \code{"as.is"}, code{"alternate"}, \code{"split"},
\code{"split.x"} or \code{"split.y"}. A value of \code{"none"} replicates
the behavior of \code{\link[ggplot2]{position_nudge}}. \code{"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.}

\item{nudge.from}{One of \code{"original"}, \code{"jittered"},
\code{"original.y"} (or \code{"jittered.x"}), \code{"original.x"} (or
\code{"jittered.y"}). A value of \code{"original"} applies the nudge before
jittering the observations, while \code{"jittered"} applies the nudging
after jittering.}

\item{kept.origin}{One of \code{"original"}, \code{"jittered"} or
\code{"none"}.}
}
\value{
A \code{"Position"} object. The layer function within it returns a
  data frame, with the jittered + nudged values in columns \code{x} and
  \code{y} and by default the jittered values with no nudging as
  \code{x_orig} and \code{y_orig}. With \code{nudge.from = "original"} the
  original values with no jitter and no nudge applied are returned as
  \code{x_orig} and \code{y_orig}.
}
\description{
\code{position_jitternudge()} combines into one function the action of
\code{\link[ggplot2]{position_jitter}} and
\code{\link[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.
}
\details{
Jitter with \code{position_jitternudge()} is identical to that with
  \code{\link[ggplot2]{position_jitter}} while nudging is enhanced compared
  to \code{\link[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 points in a plot. In this case, it is mandatory to use the same
  arguments to \code{width}, \code{height} and \code{seed} when passing
  \code{position_jitter()} to \code{geom_point()} and
  \code{position_jitternudge()} to \code{geom_text()} or to
  \code{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
  \code{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 \code{origin = "original"} to override the
  default \code{origin = "jittered"}.
}
\note{
When \code{direction = "split"} is used together with no jitter, the
  split to left and right, or up and down is done at random.
}
\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")))

}
\seealso{
\code{\link[ggplot2]{position_jitter}},
\code{\link[ggplot2]{position_nudge}},
 \code{\link[ggrepel]{position_nudge_repel}}.

Other position adjustments: 
\code{\link{position_dodgenudge}()},
\code{\link{position_nudge_center}()},
\code{\link{position_nudge_line}()},
\code{\link{position_nudge_to}()},
\code{\link{position_stacknudge}()}
}
\author{
Michał Krassowski, edited by Pedro J. Aphalo.
}
\concept{position adjustments}