boxplot.stats              package:base              R Documentation

Box Plot Statistics

Description:

     This function is typically called by `boxplot' to gather the
     statistics necessary for producing box plots, but may be invoked
     separately.

Usage:

     boxplot.stats(x, coef = 1.5, do.conf=TRUE, do.out=TRUE)

Arguments:

       x: a numeric vector for which the boxplot will be constructed
          (`NA's and `NaN's are allowed and omitted).

    coef: this determines how far the plot ``whiskers'' extend out from
          the box.  If `coef' is positive, the whiskers extend to the
          most extreme data point which is no more than `coef' times
          the interquartile coef from the box.  A value of zero causes
          the whiskers to extend to the data extremes (and no outliers
          be returned).

do.conf,do.out: logicals; if `FALSE', the `conf' or `out' component
          respectively will be empty in the result.

Details:

     The two ``hinge''s are versions of the first first and third
     quartile, i.e. close to `quantile(x, c(1,3)/4)'.  The hinges equal
     the quartiles for odd n (where `n <- length(x)') and differ for
     even n. Where the quartiles only equal observations for `n %% 4 ==
     1' (n = 1 mod 4), the hinges do so additionally for `n %% 4 == 2'
     (n = 2 mod 4), and are in the middle of two observations
     otherwise.

Value:

     List with named components as follows: 

   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.

       n: the number of of non-`NA' observations in the sample.

    conf: the lower and upper extremes of the ``notch''
          (`if(do.conf)').

     out: the values of any data points which lie beyond the extremes
          of the whiskers (`if(do.out)').


     Note that `$stats' and `$conf' are sorted in increasing order,
     unlike S, and that `$n' and `$out' include any `+- Inf' values.

See Also:

     `fivenum', `boxplot', `bxp'.

Examples:

     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))

