boxplot.stats {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 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).
`do.conf,do.out` | logicals; if `FALSE`, the `conf` or `out` component respectively will be empty in the result.

### Details

The two ``hinges'' 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))

[Package Contents]