boxplot                 package: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"))

