boxplot {base} | R Documentation

## Box Plots

### Description

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

### Usage

    boxplot(x, ..., range = 1.5, width = NULL, varwidth = FALSE,
            notch = FALSE, outline = TRUE, names, boxwex = 0.8, plot = TRUE,
            border = par("fg"), col = NULL, log = "", pars = NULL,
            horizontal = FALSE, add = FALSE, at = NULL)

### Arguments

`x, ...` | for specifying data from which the boxplots are to be produced as well as for giving graphical parameters. The named arguments in this (more precisely, in `list(x, ...)`) are treated as graphical parameters in addition to the ones given by argument `pars`. The other arguments specify the data, either as separate vectors, each corresponding to a component boxplot, or as a single list containing such vectors. `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.
`outline` | if `outline` is not true, the boxplot lines are not drawn.
`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.
`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.
`at` | numeric vector giving the locations where the boxplots should be drawn, particularly when `add = TRUE`; defaults to `1:n` where `n` is the number of boxes.

### Details

The generic function `boxplot` 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.formula` for the formula interface; `boxplot.stats` which does the computation, `bxp` for the plotting; and `stripchart` 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")

    rb <- boxplot(decrease ~ treatment, data = OrchardSprays, col="bisque")
    title("Comparing boxplot()s and non-robust mean +/- SD")

    mn.t <- tapply(OrchardSprays$decrease, OrchardSprays$treatment, mean)
    sd.t <- tapply(OrchardSprays$decrease, OrchardSprays$treatment, sd)
    xi <- 0.3 + seq(rb$n)
    points(xi, mn.t, col = "orange", pch = 18)
    arrows(xi, mn.t - sd.t, xi, mn.t + sd.t,
           code = 3, col = "pink", angle = 75, length = .1)

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

    ## Using `at = ' and adding boxplots -- example idea by Roger Bivand :

    data(ToothGrowth)
    boxplot(len ~ dose, data = ToothGrowth,
            boxwex = 0.25, at = 1:3 - 0.2,
            subset= supp == "VC", col="yellow",
            main="Guinea Pigs' Tooth Growth",
            xlab="Vitamin C dose mg",
            ylab="tooth length", ylim=c(0,35))
    boxplot(len ~ dose, data = ToothGrowth, add = TRUE,
            boxwex = 0.25, at = 1:3 + 0.2,
            subset= supp == "OJ", col="orange")
    legend(2, 9, c("Ascorbic acid", "Orange juice"),
           fill = c("yellow", "orange"))

[Package Contents]