1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/position-dodge.r, R/position-dodge2.r
3\name{position_dodge}
4\alias{position_dodge}
5\alias{position_dodge2}
6\title{Dodge overlapping objects side-to-side}
7\usage{
8position_dodge(width = NULL, preserve = c("total", "single"))
9
10position_dodge2(
11  width = NULL,
12  preserve = c("total", "single"),
13  padding = 0.1,
14  reverse = FALSE
15)
16}
17\arguments{
18\item{width}{Dodging width, when different to the width of the individual
19elements. This is useful when you want to align narrow geoms with wider
20geoms. See the examples.}
21
22\item{preserve}{Should dodging preserve the total width of all elements
23at a position, or the width of a single element?}
24
25\item{padding}{Padding between elements at the same position. Elements are
26shrunk by this proportion to allow space between them. Defaults to 0.1.}
27
28\item{reverse}{If \code{TRUE}, will reverse the default stacking order.
29This is useful if you're rotating both the plot and legend.}
30}
31\description{
32Dodging preserves the vertical position of an geom while adjusting the
33horizontal position. \code{position_dodge()} requires the grouping variable to be
34be specified in the global or \verb{geom_*} layer. Unlike \code{position_dodge()},
35\code{position_dodge2()} works without a grouping variable in a layer.
36\code{position_dodge2()} works with bars and rectangles, but is
37particulary useful for arranging box plots, which
38can have variable widths.
39}
40\examples{
41ggplot(mtcars, aes(factor(cyl), fill = factor(vs))) +
42  geom_bar(position = "dodge2")
43
44# By default, dodging with `position_dodge2()` preserves the total width of
45# the elements. You can choose to preserve the width of each element with:
46ggplot(mtcars, aes(factor(cyl), fill = factor(vs))) +
47  geom_bar(position = position_dodge2(preserve = "single"))
48
49\donttest{
50ggplot(diamonds, aes(price, fill = cut)) +
51  geom_histogram(position="dodge2")
52# see ?geom_bar for more examples
53
54# In this case a frequency polygon is probably a better choice
55ggplot(diamonds, aes(price, colour = cut)) +
56  geom_freqpoly()
57}
58
59# Dodging with various widths -------------------------------------
60# To dodge items with different widths, you need to be explicit
61df <- data.frame(
62  x = c("a","a","b","b"),
63  y = 2:5,
64  g = rep(1:2, 2)
65)
66p <- ggplot(df, aes(x, y, group = g)) +
67  geom_col(position = "dodge", fill = "grey50", colour = "black")
68p
69
70# A line range has no width:
71p + geom_linerange(aes(ymin = y - 1, ymax = y + 1), position = "dodge")
72
73# So you must explicitly specify the width
74p + geom_linerange(
75  aes(ymin = y - 1, ymax = y + 1),
76  position = position_dodge(width = 0.9)
77)
78
79# The same principle applies to error bars, which are usually
80# narrower than the bars
81p + geom_errorbar(
82  aes(ymin = y - 1, ymax = y + 1),
83  width = 0.2,
84  position = "dodge"
85)
86p + geom_errorbar(
87  aes(ymin = y - 1, ymax = y + 1),
88  width = 0.2,
89  position = position_dodge(width = 0.9)
90)
91
92# Box plots use position_dodge2 by default, and bars can use it too
93ggplot(mpg, aes(factor(year), displ)) +
94  geom_boxplot(aes(colour = hwy < 30))
95
96ggplot(mpg, aes(factor(year), displ)) +
97  geom_boxplot(aes(colour = hwy < 30), varwidth = TRUE)
98
99ggplot(mtcars, aes(factor(cyl), fill = factor(vs))) +
100  geom_bar(position = position_dodge2(preserve = "single"))
101
102ggplot(mtcars, aes(factor(cyl), fill = factor(vs))) +
103  geom_bar(position = position_dodge2(preserve = "total"))
104}
105\seealso{
106Other position adjustments:
107\code{\link{position_identity}()},
108\code{\link{position_jitterdodge}()},
109\code{\link{position_jitter}()},
110\code{\link{position_nudge}()},
111\code{\link{position_stack}()}
112}
113\concept{position adjustments}
114