% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/position-dodge-nudge.R,
%   R/position-dodge2-nudge.R
\name{position_dodgenudge}
\alias{position_dodgenudge}
\alias{position_dodge_keep}
\alias{position_dodge2nudge}
\alias{position_dodge2_keep}
\title{Combined positions dodge and nudge}
\source{
\url{https://github.com/slowkow/ggrepel/issues/161}.
}
\usage{
position_dodgenudge(
  width = 1,
  preserve = c("total", "single"),
  reverse = FALSE,
  x = 0,
  y = 0,
  direction = c("none", "split", "split.x", "split.y", "center"),
  kept.origin = c("dodged", "original", "none")
)

position_dodge_keep(
  width = 1,
  preserve = c("total", "single"),
  reverse = FALSE,
  kept.origin = "original"
)

position_dodge2nudge(
  width = 1,
  preserve = c("total", "single"),
  padding = 0.1,
  reverse = FALSE,
  x = 0,
  y = 0,
  direction = c("none", "split", "split.x", "split.y", "center"),
  kept.origin = c("dodged", "original", "none")
)

position_dodge2_keep(
  width = 1,
  preserve = c("total", "single"),
  kept.origin = "original"
)
}
\arguments{
\item{width}{Dodging width, when different to the width of the individual
elements. This is useful when you want to align narrow geoms with wider
geoms. See the examples.}

\item{preserve}{Should dodging preserve the total width of all elements at a
position, or the width of a single element?.}

\item{reverse}{If TRUE, will reverse the default stacking order. This is
useful if you're rotating both the plot and legend.}

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

\item{direction}{One of \code{"none"}, \code{"split"}, \code{"split.x"} or
\code{"split.y"}. A value of \code{"none"} replicates the behavior of
\code{\link[ggplot2]{position_nudge}}. At the moment \code{"split"} changes
the sign of the nudge at zero, which is suitable for column plots with
negative slices.}

\item{kept.origin}{One of \code{"original"}, \code{"dodged"} or
\code{"none"}.}

\item{padding}{Padding between elements at the same position. Elements are
shrunk by this proportion to allow space between them. Defaults to 0.1.}
}
\value{
A \code{"Position"} object.
}
\description{
\code{position_dodgenudge()} combines into one function the action of
\code{\link[ggplot2]{position_dodge}} and
\code{\link[ggplot2]{position_nudge}} and \code{position_dodge2nudge()}
combines into one function the action of
\code{\link[ggplot2]{position_dodge2}} and
\code{\link[ggplot2]{position_nudge}}. They are useful when labelling plots
such as grouped bars, columns, etc. and when adding dodged text labels linked
to observations plotted without dodge. It can replace other position
functions as they are backwards compatible. Like all other position functions
in 'ggpp' and 'ggrepel' they preserve the initial position to allow drawing
of segments or arrow linking the original position to the displaced one.
}
\details{
The applied dodge is identical to that by
  \code{\link[ggplot2]{position_dodge}} or
  \code{\link[ggplot2]{position_dodge2}} while nudging is similar to that by
  \code{\link[ggplot2]{position_nudge}}.

There are two possible uses for these functions. First they can be used to
label dodged bars or boxplots. In this case, it is mandatory to use the same
argument to \code{width} when passing \code{position_dodge()} to
\code{geom_col()} and \code{position_dodgenudge()} to \code{geom_text()} or
\code{geom_label()} or their repulsive equivalents. Otherwise the arrows or
segments will fail to connect to the labels. In other words dodging is
computed twice. Dodge is identical to that obtained with the same arguments
in \code{\link[ggplot2]{position_dodge}} as \code{position_dodgenudge()} last
function simply calls the same code from package 'ggplot2' ahead of applying
nudging.

The second use is to dodge labels to be connected to elements that have not
been dodged.

When applying dodging, the return of original positions instead of the dodged
ones is achieved by passing \code{origin = "original"} instead of the default
of \code{origin = "dodged"}.
}
\examples{
df <- data.frame(x1 = c(1, 2, 1, 3, -1),
                 x2 = c("a", "a", "b", "b", "b"),
                 grp = c("some long name", "other name", "some name",
                         "another name", "some long name"))

# Add labels to a horizontal column plot (stacked by default)
ggplot(data = df, aes(x1, x2, group = grp)) +
  geom_col(aes(fill = grp), width = 0.8,
           position = position_dodge()) +
  geom_vline(xintercept = 0) +
  geom_text(
    aes(label = grp),
    position = position_dodgenudge(x = 0.09, direction = "split", width = 0.8),
    angle = 90, size = 3) +
  theme(legend.position = "none")

ggplot(data = df, aes(x2, x1, group = grp)) +
  geom_col(aes(fill = grp), width = 0.75,
           position = position_dodge(width = 0.75)) +
  geom_vline(xintercept = 0) +
  geom_text(aes(label = grp),
            position = position_dodgenudge(y = 0.1,
                                           direction = "split",
                                           width = 0.75),
            size = 3) +
  theme(legend.position = "none")

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

Other position adjustments:
\code{\link[=position_dodgenudge_to]{position_dodgenudge_to()}},
\code{\link[=position_jitternudge]{position_jitternudge()}},
\code{\link[=position_nudge_center]{position_nudge_center()}},
\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()}}
}
\author{
Michał Krassowski, edited by Pedro J. Aphalo.
}
\concept{position adjustments}
