\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 ``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 ``hinges'' are versions of the first 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 ``hinge'', the median, the upper ``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 ``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{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}

