boxPlot: Box Plot

In USGS-R/smwrGraphs: Graphing Functions

Box Plot

Description

Produces a truncated, simple, Tukey, or extended box plot.

Usage

boxPlot(..., group = NULL, Box = list(type = "truncated", show.counts =
  TRUE, nobox = 5, width = "Auto", fill = "none", truncated = c(10, 90)),
  yaxis.log = FALSE, yaxis.range = c(NA, NA), ylabels = "Auto",
  xlabels = "Auto", xlabels.rotate = FALSE, xtitle = "",
  ytitle = "", caption = "", margin = c(NA, NA, NA, NA))

## S3 method for class 'numeric'
boxPlot(..., group = NULL, Box = list(type =
  "truncated", show.counts = TRUE, nobox = 5, width = "Auto", fill =
  "none", truncated = c(10, 90)), yaxis.log = FALSE,
  yaxis.range = c(NA, NA), ylabels = "Auto", xlabels = "Auto",
  xlabels.rotate = FALSE, xtitle = "", ytitle = "", caption = "",
  margin = c(NA, NA, NA, NA))

## S3 method for class 'list'
boxPlot(..., group = NULL, Box = list(type =
  "truncated", show.counts = TRUE, nobox = 5, width = "Auto", fill =
  "none", truncated = c(10, 90)), yaxis.log = FALSE,
  yaxis.range = c(NA, NA), ylabels = "Auto", xlabels = "Auto",
  xlabels.rotate = FALSE, xtitle = "", ytitle = "", caption = "",
  margin = c(NA, NA, NA, NA))

## S3 method for class 'data.frame'
boxPlot(..., group = NULL, Box = list(type =
  "truncated", show.counts = TRUE, nobox = 5, width = "Auto", fill =
  "none", truncated = c(10, 90)), yaxis.log = FALSE,
  yaxis.range = c(NA, NA), ylabels = "Auto", xlabels = "Auto",
  xlabels.rotate = FALSE, xtitle = "", ytitle = "", caption = "",
  margin = c(NA, NA, NA, NA))

Arguments

...	the data to plot. Missing values are permitted and excluded from the summary statistics computations.
group	any vector containing distinct values to create groups of data for individual box plots. Missing values are not permitted. Valid only when a single numeric vector is supplied for ....
Box	control parameters for the box. See Details.
yaxis.log	logical, if TRUE, then log transform y axis.
yaxis.range	set y-axis range. See Details.
ylabels	set up y-axis labels. See linearPretty for details; the value for ylabels can be set to an valid value for the label argument in linearPretty or a tagged list with values spcified for the arguments in linearPretty.
xlabels	set up x-axis labels. Must be either "Auto" or a character vector of the x-axis labels.
xlabels.rotate	logical, if TRUE, then rotate x-axis labels 90 degrees.
xtitle	the x-axis title (also called x-axis caption).
ytitle	the y-axis title (also called y-axis caption).
caption	the figure caption
margin	set the plot area margins, in units of lines of text. Generally all NA or the output from setGraph if appropriate.

Details

If group is numeric, then the boxes will be plotted along a continuous numeric axis. Otherwise the x-axis will be discrete groups.
Box is a list with these components:

type

the type of boxtplot: "simple" the whiskers extend to the minimum and maximum of the data, "truncated" the whiskers extend to percentiles defined by truncated, "tukey" the standard "Tukey" boxplot as described by Helsel and Hirsch (200), and "extended" the whisker extend to percentiles defined by truncated and values outside of that range are shown;

show.counts

show the number of observations used to compute the boxplot statistics;

nobox

only individual values are shown if the number of observations is less than or equal to this value;

width

the width of the box, in inches;

fill

The color of the filled box or "none" for no fill;

truncated

the percentiles to use for the truncated boxplot.

For linear axes, the range can be set to virtually any pair of values. For log axes, the choice of range is more resticted—for less than one log-cycle, powers of whole numbers can be used; from 1 to about 3 log cycles, the choices should be powers of 3 or 10; and for more than 3 log cycles, the range sould be expressed only in powers of 10.

Value

Information about the graph.

Note

A call should be made to setPage to set up the graphics environment before calling boxPlot.
If yaxis.log is set to TRUE, then the quartiles and interquartile range are computed from the log-transformed values rather then the untransformed values, which is common for other box plots. Those computations are in agreement with the box plots generated in the QWGRAPH component of the QWDATA module in the National Water Information System (NWIS) described by Dennis Helsel's 1989 Branch of Systems Analysis Technical Memorandum No. 89.01, available online at https://water.usgs.gov/admin/memo/BSA/BSA89.01.pdf. Those computations have a significant effect on the appearance the whiskers and outside values of the Tukey box plot and are motivated by the general assumption of a log-normal distribution for most water-quality constituents.

References

Helsel, D.R. and Hirsch, R.M., 2002, Statistical methods in water resources: U.S. Geological Survey Techniques of Water-Resources Investigations, book 4, chap. A3, 522 p.

See Also

setPage, dotPlot

Examples

## Not run: 
set.seed(1)
Xbig <- rnorm(100)
setGD()
# The simple type box plot
boxPlot(Xbig, Box=list(type="simple"))
# For more details of boxPlot see
vignette(topic="BoxPlots", package="smwrGraphs")
vignette(topic="GraphSetup", package="smwrGraphs")
demo(topic="Coplot-simpleBoxPlot", package="smwrGraphs")

## End(Not run)

USGS-R/smwrGraphs documentation built on Oct. 11, 2022, 6:11 a.m.