boxplot {base} | R Documentation

## Box Plots

### Description

Produce box-and-whisker plot(s) of the given (grouped) values.

### Usage

    boxplot(x, ...)
    boxplot.default(x, ..., range = 1.5, width = NULL,
            varwidth = FALSE, notch = FALSE, names, boxwex = 0.8,
            data = parent.frame(), plot = TRUE,
            border = par("fg"), col = NULL, log = "", pars = NULL,
            horizontal = FALSE, add = FALSE)
    boxplot.formula(formula, data = NULL, subset, na.action, ...)

### Arguments

`x` | an R object.
`...` | methods may have additional arguments.
`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 `x ~ g` can be given, indicating that the observations in the vector `x` are to be grouped according to the levels of the `factor` `g`. In this case the argument `data` can be used to provide values for the variables in the specification. `NA`s are allowed in the data.
`range` | this determines how far the plot whiskers extend out from the box. If `range` is positive, the whiskers extend to the most extreme data point which is no more than `range` times the interquartile range from the box. A value of zero causes the whiskers to extend to the data extremes.
`width` | a vector giving the relative widths of the boxes making up the plot.
`varwidth` | if `varwidth` is `TRUE`, the boxes are drawn with widths proportional to the square-roots of the number of observations in the groups.
`notch` | if `notch` is `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.
`names` | group labels which will be printed under each boxplot.
`boxwex` | a scale factor to be applied to all boxes. When there are only a few groups, the appearance of the plot can be improved by making the boxes narrower.
`data` | `data.frame`, `list`, or `environment` in which variable names are evaluated when `x` is a formula.
`plot` | if `TRUE` (the default) then a boxplot is produced. If not, the summaries which the boxplots are based on are returned.
`border` | an optional vector of colors for the outlines of the boxplots. The values in `border` are recycled if the length of `border` is less than the number of plots.
`col` | if `col` is non-null it is assumed to contain colors to be used to col the bodies of the box plots.
`log` | character indicating if x or y or both coordinates should be plotted in log scale.
`pars` | graphical parameters can also be passed as arguments to `boxplot`.
`horizontal` | logical indicating if the boxplots should be horizontal; default `FALSE` means vertical boxes.
`add` | logical, if true add boxplot to current plot.
`formula` | a formula, such as `y ~ x`.
`data` | a data.frame (or list) from which the variables in `formula` should be taken.
`subset` | an optional vector specifying a subset of observations to be used in the fitting process.
`na.action` | a function which indicates what should happen when the data contain `NA`s.
`...` | further arguments to the default boxplot method and graphical parameters may also be passed as arguments, see `par`.

### Details

This is a generic function. It currently has a default method (`boxplot.default`) and a formula interface (`boxplot.formula`).

### Value

List with the following components:

`stats` | a matrix, each column contains the extreme of the lower whisker, the lower hinge, the median, the upper hinge and the extreme of the upper whisker for one group/plot.
`n` | a vector with the number of observations in each group.
`conf` | a matrix where each column contains the lower and upper extremes of the notch.
`out` | the values of any data points which lie beyond the extremes of the whiskers.
`group` | a vector of the same length as `out` whose elements indicate which group the outlier belongs to
`names` | a vector of names for the groups

### See Also

`boxplot.stats` which does the computation, `bxp` for the plotting, and `stripplot` for an alternative (with small data sets).

### Examples

    ## boxplot on a formula:
    data(InsectSprays)
    boxplot(count ~ spray, data = InsectSprays, col = "lightgray")
    # *add* notches (somewhat funny here):
    boxplot(count ~ spray, data = InsectSprays,
            notch = TRUE, add = TRUE, col = "blue")

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

    ## boxplot on 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 = ...)")
    par(las=1)# all axis labels horizontal
    boxplot(data.frame(mat), main = "boxplot(*, horizontal = TRUE)",
            horizontal = TRUE)