Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 235 lines (217 sloc) 9.003 kb
953fe47 @hadley Convert all documentation to roxygen
authored
1 #' Box and whiskers plot.
2 #'
ff3ef9d @wch Edits to boxplot help
wch authored
3 #' The upper and lower "hinges" correspond to the first and third quartiles
31b5358 @wch Fix boxplot help
wch authored
4 #' (the 25th and 75th percentiles). This differs slightly from the method used
ff3ef9d @wch Edits to boxplot help
wch authored
5 #' by the \code{boxplot} function, and may be apparent with small samples.
6 #' See \code{\link{boxplot.stats}} for for more information on how hinge
7 #' positions are calculated for \code{boxplot}.
b721bed @wch geom_boxplot: add docs for notch and quartile calculation
wch authored
8 #'
ff3ef9d @wch Edits to boxplot help
wch authored
9 #' The upper whisker extends from the hinge to the highest value that is within
10 #' 1.5 * IQR of the hinge, where IQR is the inter-quartile range, or distance
11 #' between the first and third quartiles. The lower whisker extends from the
119b102 Add aes pages and translate pages
unknown authored
12 #' hinge to the lowest value within 1.5 * IQR of the hinge. Data beyond the
13 #' end of the whiskers are outliers and plotted as points (as specified by Tukey).
ff3ef9d @wch Edits to boxplot help
wch authored
14 #'
15 #' In a notched box plot, the notches extend \code{1.58 * IQR / sqrt(n)}.
16 #' This gives a roughly 95% confidence interval for comparing medians.
17 #' See McGill et al. (1978) for more details.
b721bed @wch geom_boxplot: add docs for notch and quartile calculation
wch authored
18 #'
1244716 @hadley Trim whitespace
authored
19 #' @section Aesthetics:
d7971cb @hadley Fix document aesthetics.
authored
20 #' \Sexpr[results=rd,stage=build]{ggplot2:::rd_aesthetics("geom", "boxplot")}
21 #'
953fe47 @hadley Convert all documentation to roxygen
authored
22 #' @seealso \code{\link{stat_quantile}} to view quantiles conditioned on a
1244716 @hadley Trim whitespace
authored
23 #' continuous variable, \code{\link{geom_jitter}} for another way to look
953fe47 @hadley Convert all documentation to roxygen
authored
24 #' at conditional distributions"
7b5d0a7 @hadley Inherit geom parameters
authored
25 #' @inheritParams geom_point
89c6420 let geom_boxplot use the default colour, shape and size of geom_point
unknown authored
26 #' @param outlier.colour colour for outlying points. Uses the default from geom_point().
27 #' @param outlier.shape shape of outlying points. Uses the default from geom_point().
28 #' @param outlier.size size of outlying points. Uses the default from geom_point().
93e271d @wch boxplot: code cleanup, add documentation
wch authored
29 #' @param notch if \code{FALSE} (default) make a standard box plot. If
9e18812 @wch geom_boxplot: add more to notch docs
wch authored
30 #' \code{TRUE}, make a notched box plot. Notches are used to compare groups;
1244716 @hadley Trim whitespace
authored
31 #' if the notches of two boxes do not overlap, this is strong evidence that
9e18812 @wch geom_boxplot: add more to notch docs
wch authored
32 #' the medians differ.
93e271d @wch boxplot: code cleanup, add documentation
wch authored
33 #' @param notchwidth for a notched box plot, width of the notch relative to
34 #' the body (default 0.5)
1a7f86d Add parameter "varwidth" to geom_boxplot
Tomas Sieger authored
35 #' @param varwidth if \code{FALSE} (default) make a standard box plot. If
36 #' \code{TRUE}, boxes are drawn with widths proportional to the
37 #' square-roots of the number of observations in the groups (possibly
5dc188a Adressing Hadley Wickham's suggestions to #927
Tomas Sieger authored
38 #' weighted, using the \code{weight} aesthetic).
953fe47 @hadley Convert all documentation to roxygen
authored
39 #' @export
b721bed @wch geom_boxplot: add docs for notch and quartile calculation
wch authored
40 #'
41 #' @references McGill, R., Tukey, J. W. and Larsen, W. A. (1978) Variations of
42 #' box plots. The American Statistician 32, 12-16.
43 #'
953fe47 @hadley Convert all documentation to roxygen
authored
44 #' @examples
c5b872e @hadley Don't test any example that takes over 5 seconds
authored
45 #' \donttest{
953fe47 @hadley Convert all documentation to roxygen
authored
46 #' p <- ggplot(mtcars, aes(factor(cyl), mpg))
1244716 @hadley Trim whitespace
authored
47 #'
953fe47 @hadley Convert all documentation to roxygen
authored
48 #' p + geom_boxplot()
49 #' qplot(factor(cyl), mpg, data = mtcars, geom = "boxplot")
1244716 @hadley Trim whitespace
authored
50 #'
953fe47 @hadley Convert all documentation to roxygen
authored
51 #' p + geom_boxplot() + geom_jitter()
52 #' p + geom_boxplot() + coord_flip()
53 #' qplot(factor(cyl), mpg, data = mtcars, geom = "boxplot") +
54 #' coord_flip()
4f3356e @wch Added notch option to boxplot.
wch authored
55 #'
5e1e187 @wch Code cleanup for notched boxplot.
wch authored
56 #' p + geom_boxplot(notch = TRUE)
57 #' p + geom_boxplot(notch = TRUE, notchwidth = .3)
1244716 @hadley Trim whitespace
authored
58 #'
953fe47 @hadley Convert all documentation to roxygen
authored
59 #' p + geom_boxplot(outlier.colour = "green", outlier.size = 3)
1244716 @hadley Trim whitespace
authored
60 #'
953fe47 @hadley Convert all documentation to roxygen
authored
61 #' # Add aesthetic mappings
1244716 @hadley Trim whitespace
authored
62 #' # Note that boxplots are automatically dodged when any aesthetic is
953fe47 @hadley Convert all documentation to roxygen
authored
63 #' # a factor
64 #' p + geom_boxplot(aes(fill = cyl))
65 #' p + geom_boxplot(aes(fill = factor(cyl)))
66 #' p + geom_boxplot(aes(fill = factor(vs)))
67 #' p + geom_boxplot(aes(fill = factor(am)))
1244716 @hadley Trim whitespace
authored
68 #'
953fe47 @hadley Convert all documentation to roxygen
authored
69 #' # Set aesthetics to fixed value
1f269f0 @JakeRuss Style changes to boxplot & added aes-colour-fill-alpha.r
JakeRuss authored
70 #' p + geom_boxplot(fill = "grey80", colour = "#3366FF")
1244716 @hadley Trim whitespace
authored
71 #' qplot(factor(cyl), mpg, data = mtcars, geom = "boxplot",
953fe47 @hadley Convert all documentation to roxygen
authored
72 #' colour = I("#3366FF"))
1244716 @hadley Trim whitespace
authored
73 #'
953fe47 @hadley Convert all documentation to roxygen
authored
74 #' # Scales vs. coordinate transforms -------
75 #' # Scale transformations occur before the boxplot statistics are computed.
76 #' # Coordinate transformations occur afterwards. Observe the effect on the
77 #' # number of outliers.
3d8b389 @hadley Checking examples. Up to geom_blank.Rd
authored
78 #' library(plyr) # to access round_any
953fe47 @hadley Convert all documentation to roxygen
authored
79 #' m <- ggplot(movies, aes(y = votes, x = rating,
80 #' group = round_any(rating, 0.5)))
81 #' m + geom_boxplot()
82 #' m + geom_boxplot() + scale_y_log10()
83 #' m + geom_boxplot() + coord_trans(y = "log10")
84 #' m + geom_boxplot() + scale_y_log10() + coord_trans(y = "log10")
1244716 @hadley Trim whitespace
authored
85 #'
953fe47 @hadley Convert all documentation to roxygen
authored
86 #' # Boxplots with continuous x:
87 #' # Use the group aesthetic to group observations in boxplots
88 #' qplot(year, budget, data = movies, geom = "boxplot")
1244716 @hadley Trim whitespace
authored
89 #' qplot(year, budget, data = movies, geom = "boxplot",
953fe47 @hadley Convert all documentation to roxygen
authored
90 #' group = round_any(year, 10, floor))
342ca5f @JakeRuss Added examples to geom_bar & geom_boxplot
JakeRuss authored
91 #'
75ee598 @JakeRuss Style changes
JakeRuss authored
92 #' # Using precomputed statistics
93 #' # generate sample data
1f269f0 @JakeRuss Style changes to boxplot & added aes-colour-fill-alpha.r
JakeRuss authored
94 #' abc <- adply(matrix(rnorm(100), ncol = 5), 2, quantile, c(0, .25, .5, .75, 1))
0406725 @hadley Fix line widths
authored
95 #' b <- ggplot(abc, aes(x = X1, ymin = `0%`, lower = `25%`,
96 #' middle = `50%`, upper = `75%`, ymax = `100%`))
1f269f0 @JakeRuss Style changes to boxplot & added aes-colour-fill-alpha.r
JakeRuss authored
97 #' b + geom_boxplot(stat = "identity")
98 #' b + geom_boxplot(stat = "identity") + coord_flip()
99 #' b + geom_boxplot(aes(fill = X1), stat = "identity")
1a7f86d Add parameter "varwidth" to geom_boxplot
Tomas Sieger authored
100 #'
101 #' # Using varwidth
102 #' p + geom_boxplot(varwidth = TRUE)
103 #' qplot(factor(cyl), mpg, data = mtcars, geom = "boxplot", varwidth = TRUE)
cf5733c @hadley Merge branch 'master' of github.com:ThierryO/ggplot2 into ThierryO-ma…
authored
104 #'
89c6420 let geom_boxplot use the default colour, shape and size of geom_point
unknown authored
105 #' # Update the defaults for the outliers by changing the defaults for geom_point
cf5733c @hadley Merge branch 'master' of github.com:ThierryO/ggplot2 into ThierryO-ma…
authored
106 #'
89c6420 let geom_boxplot use the default colour, shape and size of geom_point
unknown authored
107 #' p <- ggplot(mtcars, aes(factor(cyl), mpg))
108 #' p + geom_boxplot()
cf5733c @hadley Merge branch 'master' of github.com:ThierryO/ggplot2 into ThierryO-ma…
authored
109 #'
89c6420 let geom_boxplot use the default colour, shape and size of geom_point
unknown authored
110 #' update_geom_defaults("point", list(shape = 1, colour = "red", size = 5))
111 #' p + geom_boxplot()
c5b872e @hadley Don't test any example that takes over 5 seconds
authored
112 #' }
cf5733c @hadley Merge branch 'master' of github.com:ThierryO/ggplot2 into ThierryO-ma…
authored
113 geom_boxplot <- function (mapping = NULL, data = NULL, stat = "boxplot",
114 position = "dodge", outlier.colour = NULL,
115 outlier.shape = NULL, outlier.size = NULL,
ecbce50 @hadley Add back in accidentally removed varwidth param
authored
116 notch = FALSE, notchwidth = .5, varwidth = FALSE,
117 ...) {
cf5733c @hadley Merge branch 'master' of github.com:ThierryO/ggplot2 into ThierryO-ma…
authored
118
89c6420 let geom_boxplot use the default colour, shape and size of geom_point
unknown authored
119 outlier_defaults <- Geom$find('point')$default_aes()
cf5733c @hadley Merge branch 'master' of github.com:ThierryO/ggplot2 into ThierryO-ma…
authored
120
89c6420 let geom_boxplot use the default colour, shape and size of geom_point
unknown authored
121 outlier.colour <- outlier.colour %||% outlier_defaults$colour
122 outlier.shape <- outlier.shape %||% outlier_defaults$shape
123 outlier.size <- outlier.size %||% outlier_defaults$size
cf5733c @hadley Merge branch 'master' of github.com:ThierryO/ggplot2 into ThierryO-ma…
authored
124
1244716 @hadley Trim whitespace
authored
125 GeomBoxplot$new(mapping = mapping, data = data, stat = stat,
cf5733c @hadley Merge branch 'master' of github.com:ThierryO/ggplot2 into ThierryO-ma…
authored
126 position = position, outlier.colour = outlier.colour,
127 outlier.shape = outlier.shape, outlier.size = outlier.size, notch = notch,
ecbce50 @hadley Add back in accidentally removed varwidth param
authored
128 notchwidth = notchwidth, varwidth = varwidth, ...)
ede677c @JakeRuss Removed xxx.r (build_accessor file) and @name tags, added functions t…
JakeRuss authored
129 }
130
cbeacb6 @hadley Massive rewrite to better deal with xmin, xmax, xend etc
authored
131 GeomBoxplot <- proto(Geom, {
46c1796 @hadley Fix loading problems
authored
132 objname <- "boxplot"
133
ef2f944 @hadley Fix height and width settings.
authored
134 reparameterise <- function(., df, params) {
1244716 @hadley Trim whitespace
authored
135 df$width <- df$width %||%
ef2f944 @hadley Fix height and width settings.
authored
136 params$width %||% (resolution(df$x, FALSE) * 0.9)
b3d6150 @kohske Fix a but in boxplot: now correctly identify the range of data includ…
kohske authored
137
0d46c52 @hadley Check for outliers in geom_boxplot
authored
138 if (!is.null(df$outliers)) {
139 suppressWarnings({
140 out_min <- vapply(df$outliers, min, numeric(1))
141 out_max <- vapply(df$outliers, max, numeric(1))
142 })
1244716 @hadley Trim whitespace
authored
143
0d46c52 @hadley Check for outliers in geom_boxplot
authored
144 df$ymin_final <- pmin(out_min, df$ymin)
145 df$ymax_final <- pmax(out_max, df$ymax)
1244716 @hadley Trim whitespace
authored
146 }
147
5dc188a Adressing Hadley Wickham's suggestions to #927
Tomas Sieger authored
148 # if `varwidth` not requested or not available, don't use it
149 if (is.null(params) || is.null(params$varwidth) || !params$varwidth || is.null(df$relvarwidth)) {
150 df$xmin <- df$x - df$width / 2
151 df$xmax <- df$x + df$width / 2
1a7f86d Add parameter "varwidth" to geom_boxplot
Tomas Sieger authored
152 } else {
5dc188a Adressing Hadley Wickham's suggestions to #927
Tomas Sieger authored
153 # make `relvarwidth` relative to the size of the largest group
154 df$relvarwidth <- df$relvarwidth / max(df$relvarwidth)
155 df$xmin <- df$x - df$relvarwidth * df$width / 2
156 df$xmax <- df$x + df$relvarwidth * df$width / 2
1a7f86d Add parameter "varwidth" to geom_boxplot
Tomas Sieger authored
157 }
5dc188a Adressing Hadley Wickham's suggestions to #927
Tomas Sieger authored
158 df$width <- NULL
159 if (!is.null(df$relvarwidth)) df$relvarwidth <- NULL
ba1a091 @kohske quick fix of incorrect automatic range for geom_box (#274)
kohske authored
160
5dc188a Adressing Hadley Wickham's suggestions to #927
Tomas Sieger authored
161 df
160fe60 @hadley geom_boxplot fixes.
authored
162 }
1244716 @hadley Trim whitespace
authored
163
4f3356e @wch Added notch option to boxplot.
wch authored
164 draw <- function(., data, ..., fatten = 2, outlier.colour = NULL, outlier.shape = NULL, outlier.size = 2,
1a7f86d Add parameter "varwidth" to geom_boxplot
Tomas Sieger authored
165 notch = FALSE, notchwidth = .5, varwidth = FALSE) {
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
166 common <- data.frame(
1244716 @hadley Trim whitespace
authored
167 colour = data$colour,
168 size = data$size,
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
169 linetype = data$linetype,
1244716 @hadley Trim whitespace
authored
170 fill = alpha(data$fill, data$alpha),
6d8629c @wch geom_boxplot: assign correct group number
wch authored
171 group = data$group,
160fe60 @hadley geom_boxplot fixes.
authored
172 stringsAsFactors = FALSE
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
173 )
174
175 whiskers <- data.frame(
176 x = data$x,
1244716 @hadley Trim whitespace
authored
177 xend = data$x,
178 y = c(data$upper, data$lower),
e4e4f4a @kohske bug fix: alpha in geom-boxplot affects only the fill of box (#252).
kohske authored
179 yend = c(data$ymax, data$ymin),
84400ad @hadley Preserve alpha by default.
authored
180 alpha = NA,
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
181 common)
182
183 box <- data.frame(
1244716 @hadley Trim whitespace
authored
184 xmin = data$xmin,
185 xmax = data$xmax,
186 ymin = data$lower,
187 y = data$middle,
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
188 ymax = data$upper,
4f3356e @wch Added notch option to boxplot.
wch authored
189 ynotchlower = ifelse(notch, data$notchlower, NA),
190 ynotchupper = ifelse(notch, data$notchupper, NA),
191 notchwidth = notchwidth,
1244716 @hadley Trim whitespace
authored
192 alpha = data$alpha,
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
193 common)
1244716 @hadley Trim whitespace
authored
194
11279f6 @hadley Only draw outliers when present
authored
195 if (!is.null(data$outliers) && length(data$outliers[[1]] >= 1)) {
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
196 outliers <- data.frame(
667eec1 @hadley In boxplot, inherit size and shape from aesthetics
authored
197 y = data$outliers[[1]],
198 x = data$x[1],
199 colour = outlier.colour %||% data$colour[1],
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
200 shape = outlier.shape %||% data$shape[1],
201 size = outlier.size %||% data$size[1],
667eec1 @hadley In boxplot, inherit size and shape from aesthetics
authored
202 fill = NA,
84400ad @hadley Preserve alpha by default.
authored
203 alpha = NA,
667eec1 @hadley In boxplot, inherit size and shape from aesthetics
authored
204 stringsAsFactors = FALSE)
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
205 outliers_grob <- GeomPoint$draw(outliers, ...)
11279f6 @hadley Only draw outliers when present
authored
206 } else {
207 outliers_grob <- NULL
208 }
1244716 @hadley Trim whitespace
authored
209
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
210 ggname(.$my_name(), grobTree(
11279f6 @hadley Only draw outliers when present
authored
211 outliers_grob,
325e313 @hadley Refactoring of boxplot code. Add flatten argument
authored
212 GeomSegment$draw(whiskers, ...),
213 GeomCrossbar$draw(box, fatten = fatten, ...)
214 ))
6198457 @hadley Add ggplot
authored
215 }
216
1244716 @hadley Trim whitespace
authored
217 guide_geom <- function(.) "boxplot"
abbc246 @hadley Nice legend for boxplots. Tweak default size scale
authored
218 draw_legend <- function(., data, ...) {
219 data <- aesdefaults(data, .$default_aes(), list(...))
3e9c42b @dariobuttari Adding linetype functionality to the legend of the boxplot geom. This…
dariobuttari authored
220 gp <- with(data, gpar(col=colour, fill=alpha(fill, alpha), lwd=size * .pt, lty = linetype))
10ef695 @hadley Get expressions working as legend names
authored
221 gTree(gp = gp, children = gList(
803ef45 @wch Fix #353: alpha in boxplot legend.
wch authored
222 linesGrob(0.5, c(0.1, 0.25)),
223 linesGrob(0.5, c(0.75, 0.9)),
abbc246 @hadley Nice legend for boxplots. Tweak default size scale
authored
224 rectGrob(height=0.5, width=0.75),
225 linesGrob(c(0.125, 0.875), 0.5)
10ef695 @hadley Get expressions working as legend names
authored
226 ))
abbc246 @hadley Nice legend for boxplots. Tweak default size scale
authored
227 }
1244716 @hadley Trim whitespace
authored
228
6198457 @hadley Add ggplot
authored
229 default_stat <- function(.) StatBoxplot
230 default_pos <- function(.) PositionDodge
84400ad @hadley Preserve alpha by default.
authored
231 default_aes <- function(.) aes(weight=1, colour="grey20", fill="white", size=0.5, alpha = NA, shape = 16, linetype = "solid")
160fe60 @hadley geom_boxplot fixes.
authored
232 required_aes <- c("x", "lower", "upper", "middle", "ymin", "ymax")
6198457 @hadley Add ggplot
authored
233
ebc4d49 @kohske fix a bug (?): support transparency for the filled area of geom_boxplot.
kohske authored
234 })
Something went wrong with that request. Please try again.