\Header{boxplot}{Box Plots}
\keyword{hplot}{boxplot}
\begin{Usage}
\begin{verbatim}
boxplot(x, ..., range = 1.5, width = NULL, varwidth = FALSE,
        notch = FALSE, names.x, data = sys.frame(sys.parent()),
        plot = TRUE, border = par("fg"), col = NULL, log = "",
        pars = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x, ...}] the data from which the boxplots are to be produced.  The
data can be specified as separate vectors, each corresponding to a
component boxplot, or as a single list containing such vectors.
Alternatively a symbolic specification of the form \texttt{x $\,\tilde{\,}$ g} can
be given, indicating that the observations in the vector \texttt{x} are
to be grouped according to the levels of the \texttt{\Link{factor}}
\texttt{g}.  In this case the argument \texttt{data} can be used to
provide values for the variables in the specification.
\texttt{\Link{NA}}s are allowed in the data.
\item[\texttt{range}] this determines how far the plot whiskers extend out from
the box.  If \texttt{range} is positive, the whiskers extend to the
most extreme data point which is no more than \texttt{range} times the
interquartile range from the box.
A value of zero causes the whiskers to extend to the data extremes.
\item[\texttt{width}] a vector giving the relative widths of the boxes making
up the plot.
\item[\texttt{varwidth}] if \texttt{varwidth} is \texttt{TRUE}, the boxes are drawn
with widths proportional to the square-roots of the number of
observations in the groups.
\item[\texttt{notch}] if \texttt{notch} is \texttt{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[\texttt{names.x}] group labels which while be printed under each boxplot.
\item[\texttt{data}] \texttt{\Link{data.frame}}, \texttt{\Link{list}}, or
\texttt{\Link{environment}} in which variable names are evaluated when
\texttt{x} is a formula.
\item[\texttt{plot}] if \texttt{TRUE} (the default) then a boxplot is produced.
If not, the summaries which the boxplots are based on are returned.
\item[\texttt{border}] an optional vector of colors for the outlines of the
boxplots.  The values in \texttt{border} are recycled if the length of
\texttt{border} is less than the number of plots.
\item[\texttt{col}] if \texttt{col} is non-null it is assumed to contain colors
to be used to col the bodies of the box plots.
\item[\texttt{log}] character indicating if x- or y- or both coordinates should
be plotted in log scale.
\item[\texttt{pars, ...}] graphical parameters can also be passed as arguments to
\texttt{boxplot}.
\end{ldescription}
\end{Arguments}
\begin{Description}
Produce box-and-whisker plot(s) of the given (grouped) values.\end{Description}
\begin{Value}
List with one component corresponding to each plot.  The
components are themselves lists with named components as follows:
\begin{ldescription}
\item[\texttt{stats}] a vector containing the extreme of the lower whisker, the
lower hinge, the median, the upper hinge and the extreme of the
upper whisker.
\item[\texttt{n}] the number of observations in the sample.
\item[\texttt{conf}] the lower and upper extremes of the notch.
\item[\texttt{out}] the values of any data points which lie beyond the extremes
of the whiskers.
\end{ldescription}
\end{Value}
\begin{SeeAlso}
\texttt{\Link{boxplot.stats}} which does the computation,
\texttt{\Link{bxp}} for the plotting, and \texttt{\Link{stripplot}} for an
alternative (with small data sets).

\texttt{\Link{plot.default}} for some high-level plotting parameters.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(insects)
boxplot(count ~ spray, data = insects, col = "lightgray")

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

## boxplot(.) for 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=...)")
\end{ExampleCode}
\end{Examples}

