\Header{boxplot.stats}{Box Plot Statistics}
\keyword{dplot}{boxplot.stats}
\begin{Description}\relax
This function is typically called by \code{\Link{boxplot}} to
gather the statistics necessary for producing box plots,
but may be invoked separately.\end{Description}
\begin{Usage}
\begin{verbatim}
boxplot.stats(x, coef = 1.5, do.conf=TRUE, do.out=TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a numeric vector for which the boxplot will
be constructed (\code{\Link{NA}}s and \code{\Link{NaN}}s are allowed
and omitted).
\item[\code{coef}] this determines how far the plot \dQuote{whiskers} extend out
from the box.  If \code{coef} is positive, the whiskers extend to the
most extreme data point which is no more than \code{coef} times
the length of the box away from the box. A value of zero causes
the whiskers
to extend to the data extremes (and no outliers be returned).
\item[\code{do.conf,do.out}] logicals; if \code{FALSE}, the \code{conf} or
\code{out} component respectively will be empty in the result.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The two \dQuote{hinges} are versions of the first and third quartile,
i.e., close to \code{\Link{quantile}(x, c(1,3)/4)}.  The hinges equal
the quartiles for odd \eqn{n}{} (where \code{n <- length(x)}) and
differ for even \eqn{n}{}. Where the quartiles only equal observations
for \code{n \%\% 4 == 1} (\eqn{n\equiv 1 \bmod 4}{n = 1 mod 4}),
the hinges do so \emph{additionally} for \code{n \%\% 4 == 2}
(\eqn{n\equiv 2 \bmod 4}{n = 2 mod 4}), and are in the middle of
two observations otherwise.\end{Details}
\begin{Value}
List with named components as follows:
\begin{ldescription}
\item[\code{stats}] a vector of length 5, containing the extreme of the
lower whisker, the lower \dQuote{hinge}, the median, the upper \dQuote{hinge}
and the extreme of the upper whisker.
\item[\code{n}] the number of of non-\code{NA} observations in the sample.
\item[\code{conf}] the lower and upper extremes of the \dQuote{notch} (\code{if(do.conf)}).
\item[\code{out}] the values of any data points which lie beyond the
extremes of the whiskers (\code{if(do.out)}).
\end{ldescription}


Note that \code{\$stats} and \code{\$conf} are sorted in \emph{in}creasing
order, unlike S, and that \code{\$n} and \code{\$out} include any
\code{+- Inf} values.\end{Value}
\begin{References}\relax
Tukey, J. W. (1977) \emph{Exploratory Data Analysis.} Section 2C.

McGill, R., Tukey, J. W. and Larsen, W. A. (1978) Variations of box
plots. \emph{The American Statistician} \bold{32}, 12--16.

Velleman, P. F. and Hoaglin, D. C. (1981) \emph{Applications, Basics
and Computing of Exploratory Data Analysis.}  Duxbury Press.

Emerson, J. D and Strenio, J. (1983). Boxplots and batch comparison.
Chapter 3 of \emph{Understanding Robust and Exploratory Data
Analysis}, eds. D. C. Hoaglin, F. Mosteller and J. W. Tukey.  Wiley.\end{References}
\begin{SeeAlso}\relax
\code{\Link{fivenum}}, \code{\Link{boxplot}}, \code{\Link{bxp}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- c(1:100, 1000)
str(b1 <- boxplot.stats(x))
str(b2 <- boxplot.stats(x, do.conf=FALSE, do.out=FALSE))
stopifnot(b1 $ stats == b2 $ stats) # do.out=F is still robust
str(boxplot.stats(x, coef = 3, do.conf=FALSE))
## no outlier treatment:
str(boxplot.stats(x, coef = 0))

str(boxplot.stats(c(x, NA))) # slight change : n + 1
str(r <- boxplot.stats(c(x, -1:1/0)))
stopifnot(r$out == c(1000, -Inf, Inf))



\end{ExampleCode}
\end{Examples}

