R: Draw Box Plots from Summaries

bxp {graphics} | R Documentation

## Draw Box Plots from Summaries

### Description

`bxp` draws box plots based on the given summaries in `z`. It is usually called from within `boxplot`, but can be invoked directly.

### Usage

    bxp(z, notch = FALSE, width = NULL, varwidth = FALSE,
        outline = TRUE, notch.frac = 0.5, log = "",
        border = par("fg"), pars = NULL, frame.plot = axes,
        horizontal = FALSE, ann = TRUE,
        add = FALSE, at = NULL, show.names = NULL,
        ...)

### Arguments

`z` | a list containing data summaries to be used in constructing the plots. These are usually the result of a call to `boxplot`, but can be generated in any fashion.
`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.
`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.
`outline` | if `outline` is not true, the outliers are not drawn.
`notch.frac` | numeric in (0,1). When `notch = TRUE`, the fraction of the box width that the notches should use.
`border` | character or numeric (vector), the color of the box borders. Is recycled for multiple boxes. Is used as default for the `boxcol`, `medcol`, `whiskcol`, `staplecol`, and `outcol` options (see below).
`log` | character, indicating if any axis should be drawn in logarithmic scale, as in `plot.default`.
`frame.plot` | logical, indicating if a ‘frame’ (`box`) should be drawn; defaults to `TRUE`, unless `axes = FALSE` is specified.
`horizontal` | logical indicating if the boxplots should be horizontal; default `FALSE` means vertical boxes.
`ann` | a logical value indicating whether the default annotation (title and x and y axis labels) should appear on the plot.
`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.
`show.names` | Set to `TRUE` or `FALSE` to override the defaults on whether an x-axis label is printed for each group.
`pars,...` | graphical parameters (etc) can be passed as arguments to this function, either as a list (`pars`) or normally(`...`), see the following. (Those in `...` take precedence over those in `pars`.) Currently, `yaxs` and `ylim` are used ‘along the boxplot’, i.e., vertically, when `horizontal` is false, and `xlim` horizontally. `xaxt`, `yaxt`, `las`, `cex.axis`, and `col.axis` are passed to `axis`, and `main`, `cex.main`, `col.main`, `sub`, `cex.sub`, `col.sub`, `xlab`, `ylab`, `cex.lab`, and `col.lab` are passed to `title`. In addition, `axes` is accepted (see `plot.window`), with default `TRUE`. The following arguments (or `pars` components) allow further customization of the boxplot graphics. Their defaults are typically determined from the non-prefixed version (e.g., `boxlty` from `lty`), either from the specified argument or `pars` component or the corresponding `par` one. 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. The default depends on `at` and typically is 0.8. staplewex, outwex: staple and outlier line width expansion, proportional to box width; both default to 0.5. boxlty, boxlwd, boxcol, boxfill: box outline type, width, color, and fill color (which currently defaults to `col` and will in future default to `par("bg")`). medlty, medlwd, medpch, medcex, medcol, medbg: median line type, line width, point character, point size expansion, color, and background color. The default `medpch = NA` suppresses the point, and `medlty = "blank"` does so for the line. Note that `medlwd` defaults to 3x the default `lwd`. whisklty, whisklwd, whiskcol: whisker line type (default: `"dashed"`), width, and color. staplelty, staplelwd, staplecol: staple (= end of whisker) line type, width, and color. outlty, outlwd, outpch, outcex, outcol, outbg: outlier line type, line width, point character, point size expansion, color, and background color. The default `outlty = "blank"` suppresses the lines and `outpch = NA` suppresses points.

### Value

An invisible vector, actually identical to the `at` argument, with the coordinates ("x" if horizontal is false, "y" otherwise) of box centers, useful for adding to the plot.

### Note

When `add = FALSE`, `xlim` now defaults to `xlim = range(at, *) + c(-0.5, 0.5)`. It will usually be a good idea to specify `xlim` if the "x" axis has a log scale or `width` is far from uniform.

### Author(s)

The R Core development team and Arni Magnusson (then at U Washington) who has provided most changes for the box*, med*, whisk*, staple*, and out* arguments.

### References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

### Examples

    require(stats)
    set.seed(753)
    (bx.p <- boxplot(split(rt(100, 4), gl(5, 20))))
    op <- par(mfrow =  c(2, 2))
    bxp(bx.p, xaxt = "n")
    bxp(bx.p, notch = TRUE, axes = FALSE, pch = 4, boxfill = 1:5)
    bxp(bx.p, notch = TRUE, boxfill = "lightblue", frame = FALSE,
        outl = FALSE, main = "bxp(*, frame= FALSE, outl= FALSE)")
    bxp(bx.p, notch = TRUE, boxfill = "lightblue", border = 2:6,
        ylim = c(-4,4), pch = 22, bg = "green", log = "x",
        main = "... log = 'x', ylim = *")
    par(op)
    op <- par(mfrow = c(1, 2))

    ## single group -- no label
    boxplot (weight ~ group, data = PlantGrowth, subset = group == "ctrl")
    ## with label
    bx <- boxplot(weight ~ group, data = PlantGrowth,
                  subset = group == "ctrl", plot = FALSE)
    bxp(bx, show.names=TRUE)
    par(op)

    z <- split(rnorm(1000), rpois(1000, 2.2))
    boxplot(z, whisklty = 3, main = "boxplot(z, whisklty = 3)")

    ## Colour support similar to plot.default:
    op <- par(mfrow = 1:2, bg = "light gray", fg = "midnight blue")
    boxplot(z,   col.axis = "skyblue3", main = "boxplot(*, col.axis=..,main=..)")
    plot(z[[1]], col.axis = "skyblue3", main =    "plot(*, col.axis=..,main=..)")
    mtext("par(bg=\"light gray\", fg=\"midnight blue\")",
          outer = TRUE, line = -1.2)
    par(op)

    ## Mimic S-Plus:
    splus <- list(boxwex = 0.4, staplewex = 1, outwex = 1, boxfill = "grey40",
                  medlwd = 3, medcol = "white", whisklty = 3, outlty = 1, outpch = NA)
    boxplot(z, pars = splus)
    ## Recycled and "sweeping" parameters
    op <- par(mfrow = c(1,2))
     boxplot(z, border = 1:5, lty = 3, medlty = 1, medlwd = 2.5)
     boxplot(z, boxfill = 1:3, pch = 1:5, lwd = 1.5, medcol = "white")
    par(op)
    ## too many possibilities
    boxplot(z, boxfill = "light gray", outpch = 21:25, outlty = 2,
            bg = "pink", lwd = 2,
            medcol = "dark blue", medcex = 2, medpch = 20)

[Package graphics version 4.0.5 Index]