.BG
.VE $Header: /usr3/s/current/s/.help/RCS/boxplot,v 1.2 83/12/30 19:24:50 rab Exp $
.FN boxplot
.TL
boxplot: Box Plots
.CS
boxplot(arg1, arg2, ...,
   range=, width= varwidth=, notch=, names=, plot=)
.PP
.AG argi
numeric structure or a structure containing a number of
numeric components (e.g., the output of `split').  Missing
values (NAs) are allowed.
.AG range=
controls the strategy for the whiskers and the detached
points beyond the whiskers. By default, whiskers are drawn
to the nearest value not beyond a standard range from the quartiles; points
beyond are drawn individually.  Giving `range=0' forces
whiskers to the full data range. Any positive value of
`range' multiplies the standard range by this amount.  (The
standard range is 1.5*(inter-quartile range).)
.AG width=
vector of relative box widths.  See also argument
`varwidth'.
.AG varwidth=
logical flag.  If TRUE, box widths will be proportional to
the square-root of the number of observations for the box.
Default FALSE.
.AG notch=
logical flag.  If TRUE, notched boxes are drawn, where 
non-overlapping of notches of boxes indicates a difference at a
rough 5% significance level.  Default FALSE.
.AG names=
optional character vector of names for the groups.  If
omitted, names used in labelling the plot will be taken from
the names of the arguments and from component names of
structures.
.AG plot=
logical flag.  If TRUE, the box plot will be produced.  If
false, only the calculated summaries of the arguments are
returned.  Default TRUE.
.PP
Graphical parameters may also be supplied as arguments to this
function (see `par').
.RT
if `plot' is FALSE, a structure with the
components listed below.  Otherwise function `bxp' is
invoked with these components, plus optional
`width', `varwidth' and `notch', to produce the plot.
Note that `bxp' returns a vector of box centers.
.PP
.RC stats
matrix (5 by number of boxes) giving the upper extreme,
upper quartile, median, lower quartile, and lower extreme
for each box.
.RC n
the number of observations in each group.
.RC conf
matrix (2 by number of boxes) giving confidence limits for
median.
.RC out
optional vector of outlying points.
.RC group
vector giving the box to which each point in `out' belongs
.RC names
names for each box (see argument `names' above)
.SH REFERENCES
J. M. Chambers, W. S. Cleveland, B. Kleiner and P. A. Tukey,
.ul
Graphical Methods for Data Analysis,
Wadsworth, 1983.
.sp
McGill, Tukey and Larsen, "Variations of Box Plots",
.ul
The American Statistician,
February 1978, Vol 32, No 1, pp 12-16.
.EX
boxplot(group1,group2,group3)

boxplot(split(salary,age),varwidth=TRUE,notch=TRUE)

# the example plot is produced by:
boxplot(
      split(lottery.payoff,lottery.number%/100),
      main=lottery.label,
      sub="Leading Digit of Winning Numbers",
      ylab="Payoff")
.PI
.KW plot*
.KW hplot*
.KW dplot*
.WR
