\Header{boxplot}{Box Plots}
\methalias{boxplot.default}{boxplot}
\keyword{hplot}{boxplot}
\begin{Description}\relax
Produce box-and-whisker plot(s) of the given (grouped) values.\end{Description}
\begin{Usage}
\begin{verbatim}
boxplot(x, ..., range = 1.5, width = NULL, varwidth = FALSE,
        notch = FALSE, outline = TRUE, names, boxwex = 0.8, plot = TRUE,
        border = par("fg"), col = NULL, log = "", pars = NULL,
        horizontal = FALSE, add = FALSE, at = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, ...}] for specifying data from which the boxplots are to be
produced as well as for giving graphical parameters.  The named
arguments in this (more precisely, in \code{list(x, ...)}) are
treated as graphical parameters in addition to the ones given by
argument \code{pars}.  The other arguments specify the data, either
as separate vectors, each corresponding to a component boxplot, or
as a single list containing such vectors.  \code{\Link{NA}}s are
allowed in the data.
\item[\code{range}] this determines how far the plot whiskers extend out
from the box.  If \code{range} is positive, the whiskers extend
to the most extreme data point which is no more than
\code{range} times the interquartile range from the box. A value
of zero causes the whiskers to extend to the data extremes.
\item[\code{width}] a vector giving the relative widths of the boxes making
up the plot.
\item[\code{varwidth}] if \code{varwidth} is \code{TRUE}, the boxes are
drawn with widths proportional to the square-roots of the number
of observations in the groups.
\item[\code{notch}] if \code{notch} is \code{TRUE}, a notch is drawn in
each side of the boxes.  If the notches of two plots do not
overlap then the medians are significantly different at the 5
percent level.
\item[\code{outline}] if \code{outline} is not true, the boxplot lines are
not drawn.
\item[\code{names}] group labels which will be printed under each boxplot.
\item[\code{boxwex}] a scale factor to be applied to all boxes.  When there
are only a few groups, the appearance of the plot can be improved
by making the boxes narrower.
\item[\code{plot}] if \code{TRUE} (the default) then a boxplot is
produced.  If not, the summaries which the boxplots are based on
are returned.
\item[\code{border}] an optional vector of colors for the outlines of the
boxplots.  The values in \code{border} are recycled if the
length of \code{border} is less than the number of plots.
\item[\code{col}] if \code{col} is non-null it is assumed to contain colors
to be used to col the bodies of the box plots.
\item[\code{log}] character indicating if x or y or both coordinates should
be plotted in log scale.
\item[\code{pars}] graphical parameters can also be passed as arguments to
\code{boxplot}.
\item[\code{horizontal}] logical indicating if the boxplots should be
horizontal; default \code{FALSE} means vertical boxes.
\item[\code{add}] logical, if true \emph{add} boxplot to current plot.
\item[\code{at}] numeric vector giving the locations where the boxplots should
be drawn, particularly when \code{add = TRUE};
defaults to \code{1:n} where \code{n} is the number of boxes.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The generic function \code{boxplot} currently has a default method
(\code{boxplot.default}) and a formula interface
(\code{\Link{boxplot.formula}}).\end{Details}
\begin{Value}
List with the following components:
\begin{ldescription}
\item[\code{stats}] a matrix, each column contains the extreme of the lower
whisker, the lower hinge, the median, the upper hinge and the
extreme of the upper whisker for one group/plot.
\item[\code{n}] a vector with the number of observations in each group.
\item[\code{conf}] a matrix where each column contains the lower and upper
extremes of the notch.
\item[\code{out}] the values of any data points which lie beyond the
extremes of the whiskers.
\item[\code{group}] a vector of the same length as \code{out} whose elements
indicate which group the outlier belongs to
\item[\code{names}] a vector of names for the groups
\end{ldescription}
\end{Value}
\begin{SeeAlso}\relax
\code{\Link{boxplot.formula}} for the formula interface;
\code{\Link{boxplot.stats}} which does the computation,
\code{\Link{bxp}} for the plotting;
and \code{\Link{stripchart}} for an alternative (with small data
sets).\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## boxplot on a formula:
data(InsectSprays)
boxplot(count ~ spray, data = InsectSprays, col = "lightgray")
# *add* notches (somewhat funny here):
boxplot(count ~ spray, data = InsectSprays,
        notch = TRUE, add = TRUE, col = "blue")

data(OrchardSprays)
boxplot(decrease ~ treatment, data = OrchardSprays,
        log = "y", col="bisque")

rb <- boxplot(decrease ~ treatment, data = OrchardSprays, col="bisque")
title("Comparing boxplot()s and non-robust mean +/- SD")

mn.t <- tapply(OrchardSprays$decrease, OrchardSprays$treatment, mean)
sd.t <- tapply(OrchardSprays$decrease, OrchardSprays$treatment, sd)
xi <- 0.3 + seq(rb$n)
points(xi, mn.t, col = "orange", pch = 18)
arrows(xi, mn.t - sd.t, xi, mn.t + sd.t,
       code = 3, col = "pink", angle = 75, length = .1)

## boxplot on a matrix:
mat <- cbind(Uni05 = (1:100)/21, Norm = rnorm(100),
             T5 = rt(100, df = 5), Gam2 = rgamma(100, shape = 2))
boxplot(data.frame(mat), main = "boxplot(data.frame(mat), main = ...)")
par(las=1)# all axis labels horizontal
boxplot(data.frame(mat), main = "boxplot(*, horizontal = TRUE)",
        horizontal = TRUE)

## Using `at = ' and adding boxplots -- example idea by Roger Bivand :

data(ToothGrowth)
boxplot(len ~ dose, data = ToothGrowth,
        boxwex = 0.25, at = 1:3 - 0.2,
        subset= supp == "VC", col="yellow",
        main="Guinea Pigs' Tooth Growth",
        xlab="Vitamin C dose mg",
        ylab="tooth length", ylim=c(0,35))
boxplot(len ~ dose, data = ToothGrowth, add = TRUE,
        boxwex = 0.25, at = 1:3 + 0.2,
        subset= supp == "OJ", col="orange")
legend(2, 9, c("Ascorbic acid", "Orange juice"),
       fill = c("yellow", "orange"))
\end{ExampleCode}
\end{Examples}

