The R Project SVN R

% File src/library/graphics/man/boxplot.Rd

% Part of the R package, https://www.R-project.org

% Copyright 1995-2019 R Core Team

% Distributed under GPL 2 or later

\name{boxplot}

\alias{boxplot}

\alias{boxplot.default}

\alias{boxplot.formula}

\title{Box Plots}

\description{

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

}

\usage{

boxplot(x, \dots)

\method{boxplot}{formula}(formula, data = NULL, \dots, subset, na.action = NULL,

        xlab = mklab(y_var = horizontal),

        ylab = mklab(y_var =!horizontal),

        add = FALSE, ann = !add, horizontal = FALSE,

        drop = FALSE, sep = ".", lex.order = FALSE)

\method{boxplot}{default}(x, \dots, range = 1.5, width = NULL, varwidth = FALSE,

        notch = FALSE, outline = TRUE, names, plot = TRUE,

        border = par("fg"), col = NULL, log = "",

        pars = list(boxwex = 0.8, staplewex = 0.5, outwex = 0.5),

         ann = !add, horizontal = FALSE, add = FALSE, at = NULL)

}

\arguments{

  \item{formula}{a formula, such as \code{y ~ grp}, where \code{y} is a

    numeric vector of data values to be split into groups according to

    the grouping variable \code{grp} (usually a factor).  Note that

    \code{~ g1 + g2} is equivalent to \code{g1:g2}.}

  \item{data}{a data.frame (or list) from which the variables in

    \code{formula} should be taken.}

  \item{subset}{an optional vector specifying a subset of observations

    to be used for plotting.}

  \item{na.action}{a function which indicates what should happen

    when the data contain \code{NA}s.  The default is to ignore missing

    values in either the response or the group.}

  \item{xlab, ylab}{x- and y-axis annotation, since \R 3.6.0 with a

    non-empty default.  Can be suppressed by \code{ann=FALSE}.}

  \item{ann}{\code{\link{logical}} indicating if axes should be annotated (by

    \code{xlab} and \code{ylab}).}

  \item{drop, sep, lex.order}{passed to \code{\link{split.default}}, see there.}

  \item{x}{for specifying data from which the boxplots are to be

    produced. Either a numeric vector, or a single list containing such

    vectors. Additional unnamed arguments specify further data

    as separate vectors (each corresponding to a component boxplot).

    \code{\link{NA}}s are allowed in the data.}

  \item{\dots}{For the \code{formula} method, named arguments to be passed to

    the default method.

    For the default method, unnamed arguments are additional data

    vectors (unless \code{x} is a list when they are ignored), and named

    arguments are arguments and \link{graphical parameters} to be passed

    to \code{\link{bxp}} in addition to the ones given by argument

    \code{pars} (and override those in \code{pars}). Note that

    \code{bxp} may or may not make use of graphical parameters it is

    passed: see its documentation.

  }

  \item{range}{this determines how far the plot whiskers extend out

    from the box.  If \code{range} is positive, the whiskers extend

    to the most extreme data point which is no more than

    \code{range} times the interquartile range from the box. A value

    of zero causes the whiskers to extend to the data extremes.}

  \item{width}{a vector giving the relative widths of the boxes making

    up the plot.}

  \item{varwidth}{if \code{varwidth} is \code{TRUE}, the boxes are

    drawn with widths proportional to the square-roots of the number

    of observations in the groups.}

  \item{notch}{if \code{notch} is \code{TRUE}, a notch is drawn in

    each side of the boxes.  If the notches of two plots do not

    overlap this is \sQuote{strong evidence} that the two medians differ

    (Chambers \emph{et al}, 1983, p.\sspace{}62).  See \code{\link{boxplot.stats}}

    for the calculations used.}

  \item{outline}{if \code{outline} is not true, the outliers are

    not drawn (as points whereas S+ uses lines).}% the argument name is most ugly but S+ compatible

  \item{names}{group labels which will be printed under each boxplot.

    Can be a character vector or an \link{expression} (see

    \link{plotmath}).}

  \item{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.}

  \item{staplewex}{staple line width expansion, proportional to box

    width.}

  \item{outwex}{outlier line width expansion, proportional to box

    width.}

  \item{plot}{if \code{TRUE} (the default) then a boxplot is

    produced.  If not, the summaries which the boxplots are based on

    are returned.}

  \item{border}{an optional vector of colors for the outlines of the

    boxplots.  The values in \code{border} are recycled if the

    length of \code{border} is less than the number of plots.}

  \item{col}{if \code{col} is non-null it is assumed to contain colors

    to be used to colour the bodies of the box plots. By default they

    are in the background colour.}

  \item{log}{character indicating if x or y or both coordinates should

    be plotted in log scale.}

  \item{pars}{a list of (potentially many) more graphical parameters,

    e.g., \code{boxwex} or \code{outpch}; these are passed to

    \code{\link{bxp}} (if \code{plot} is true); for details, see there.}

  \item{horizontal}{logical indicating if the boxplots should be

    horizontal; default \code{FALSE} means vertical boxes.}

  \item{add}{logical, if true \emph{add} boxplot to current plot.}

  \item{at}{numeric vector giving the locations where the boxplots should

    be drawn, particularly when \code{add = TRUE};

    defaults to \code{1:n} where \code{n} is the number of boxes.}

}

\details{

  The generic function \code{boxplot} currently has a default method

  (\code{boxplot.default}) and a formula interface (\code{boxplot.formula}).

  If multiple groups are supplied either as multiple arguments or via a

  formula, parallel boxplots will be plotted, in the order of the

  arguments or the order of the levels of the factor (see

  \code{\link{factor}}).

  Missing values are ignored when forming boxplots.

}

\value{

  List with the following components:

  \item{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.  If all the inputs

    have the same class attribute, so will this component.}

  \item{n}{a vector with the number of (non-\code{\link{NA}}) observations in each group.}

  \item{conf}{a matrix where each column contains the lower and upper

    extremes of the notch.}

  \item{out}{the values of any data points which lie beyond the

    extremes of the whiskers.}

  \item{group}{a vector of the same length as \code{out} whose elements

    indicate to which group the outlier belongs.}

  \item{names}{a vector of names for the groups.}

}

\references{

  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988).

  \emph{The New S Language}.

  Wadsworth & Brooks/Cole.

  Chambers, J. M., Cleveland, W. S., Kleiner, B. and Tukey, P. A. (1983).

  \emph{Graphical Methods for Data Analysis}.

  Wadsworth & Brooks/Cole.

  Murrell, P. (2005).

  \emph{R Graphics}.

  Chapman & Hall/CRC Press.

  See also \code{\link{boxplot.stats}}.

}

\seealso{

  \code{\link{boxplot.stats}} which does the computation,

  \code{\link{bxp}} for the plotting and more examples;

  and \code{\link{stripchart}} for an alternative (with small data

  sets).

}

\examples{

## boxplot on a formula:

boxplot(count ~ spray, data = InsectSprays, col = "lightgray")

# *add* notches (somewhat funny here <--> warning "notches .. outside hinges"):

boxplot(count ~ spray, data = InsectSprays,

        notch = TRUE, add = TRUE, col = "blue")

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

        log = "y")

## horizontal=TRUE, switching  y <--> x :

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

        log = "x", horizontal=TRUE)

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

             `5T` = rt(100, df = 5), Gam2 = rgamma(100, shape = 2))

boxplot(mat) # directly, calling boxplot.matrix()

## boxplot on a data frame:

df. <- as.data.frame(mat)

par(las = 1) # all axis labels horizontal

boxplot(df., main = "boxplot(*, horizontal = TRUE)", horizontal = TRUE)

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

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",

        xlim = c(0.5, 3.5), ylim = c(0, 35), yaxs = "i")

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

## With less effort (slightly different) using factor *interaction*:

boxplot(len ~ dose:supp, data = ToothGrowth,

        boxwex = 0.5, col = c("orange", "yellow"),

        main = "Guinea Pigs' Tooth Growth",

        xlab = "Vitamin C dose mg", ylab = "tooth length",

        sep = ":", lex.order = TRUE, ylim = c(0, 35), yaxs = "i")

## more examples in  help(bxp)

}

\keyword{hplot}