# errorBar: Plot Pointwise Error Bars In EnvStats: Package for Environmental Statistics, Including US EPA Guidance

## Description

Plot pointwise error bars given their upper and lower limits.

The `errorBar` function is a modified version of the S function `error.bar`. The EnvStats function `errorBar` includes the additional arguments `draw.lower`, `draw.upper`, `gap.size`, `bar.ends.size`, and `col` to determine whether both the lower and upper error bars are drawn and to control the size of the gaps, the size of the bar ends, and the color of the bars.

## Usage

 ```1 2 3 4``` ``` errorBar(x, y = NULL, lower, upper, incr = TRUE, draw.lower = TRUE, draw.upper = TRUE, bar.ends = TRUE, gap = TRUE, add = FALSE, horizontal = FALSE, gap.size = 0.75, bar.ends.size = 1, col = 1, ..., xlab = deparse(substitute(x)), xlim, ylim) ```

## Arguments

 `x, y` coordinates of points. The coordinates can be given by two vector arguments or by a single vector `x`. When both `x` and `y` are supplied and `horizontal=FALSE` (see below), `x` specifies where the groups will be plotted on the x-axis and `y` denotes the centers for each group that will be plotted on the y-axis. When both `x` and `y` are supplied and `horizontal=TRUE` (see below), `y` specifies where the groups will be plotted on the y-axis and `x` denotes the centers for each group that will be plotted on the x-axis. If a single numeric vector is given, then `time(x)` is plotted on the x-axis and `x` is plotted on the y-axis. Missing values (`NA`s) are allowed; points containing missing values are omitted from the plot. `lower` pointwise lower limits of the error bars. This may be a single number or a vector the same length as `x` and `y`. If `incr=TRUE`, then `lower` is expected to contain the lower half widths of the error bars. If `incr=FALSE`, then `lower` contains the coordinates of the lower limits in terms of `x` or `y`, depending on the orientation of the bars. `upper` pointwise upper limits of the error bars. This may be a single number or a vector the same length as `x` and `y`. If `incr=TRUE`, then `upper` is expected to contain the upper half widths of the error bars. If `incr=FALSE`, then upper contains the coordinates of the upper limits in terms of `x` or `y`, depending on the orientation of the bars. If `upper` is missing, the upper limits are drawn symmetric to the lower limits. `incr` logical scalar indicating whether the values in `lower` and `upper` represent increments. If `incr=TRUE` (the default), then `lower` and `upper` are assumed to represent half the widths of the error bars (increments). `draw.lower` logical scalar indicating whether to draw the lower error bar. The default is `draw.lower=TRUE`. `draw.upper` logical scalar indicating whether to draw the upper error bar. The default is `draw.upper=TRUE`. `bar.ends` logical scalar indicating whether flat bars should be drawn at the endpoints. The default is `bar.ends=TRUE`. `gap` logical scalar indicating whether gaps should be left around the points to emphasize their locations. The default is `gap=TRUE`. `add` logical scalar indicating whether error bars should be added to the current plot. If `add=TRUE` and a graphics device is open, the error bars are added to the plot in the open device and no axes are drawn. In this case, you should use the plot parameters `xlim` and `ylim` to provide enough room for the error bars; otherwise, “Lines out of bounds” warnings are generated. If `add=FALSE` (the default), a new coordinate system is set up for the error bar plot and axes are drawn. `horizontal` logical scalar indicating whether the error bars should be oriented horizontally (`horizontal=TRUE`) or vertically (`horizontal=FALSE`; the default). `gap.size` numeric scalar controlling the width of the gap. `bar.ends.size` numeric scalar controlling the length of the bar ends. `col` numeric or character vector indicating the color(s) of the bars. `xlab, xlim, ylim, ...` additional graphical parameters (see `par`).

## Details

`errorBar` creates a plot of `y` versus `x` with pointwise error bars.

## Value

`errorBar` invisibly returns a list with the following components:

 `group.centers` numeric vector of values on the group axis (the x-axis unless `horizontal=TRUE`) indicating the centers of the groups. `group.stats` a matrix with the number of rows equal to the number of groups and three columns indicating the group location parameter (Center), the lower limit for the error bar (Lower), and the upper limit for the error bar (Upper).

## Author(s)

Authors of S (for code for `error.bar` in S).

Steven P. Millard (EnvStats@ProbStatInfo.com)

## References

Cleveland, W.S. (1994). The Elements of Graphing Data. Hobart Press, Summit, New Jersey.

## See Also

`plot`, `segments`, `pointwise`, `stripChart`.

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46``` ``` # The guidance document USEPA (1994b, pp. 6.22--6.25) # contains measures of 1,2,3,4-Tetrachlorobenzene (TcCB) # concentrations (in parts per billion) from soil samples # at a Reference area and a Cleanup area. These data are strored # in the data frame EPA.94b.tccb.df. # # Using the log-transformed data, create # # 1. A dynamite plot (bar plot showing mean plus 1 SE) # # 2. A confidence interval plot. TcCB.mat <- summaryStats(TcCB ~ Area, data = EPA.94b.tccb.df, se = TRUE, ci = TRUE) Means <- TcCB.mat[, "Mean"] SEs <- TcCB.mat[, "SE"] LCLs <- TcCB.mat[, "95%.LCL"] UCLs <- TcCB.mat[, "95%.UCL"] # Dynamite Plot #-------------- dev.new() group.centers <- barplot(Means, col = c("red", "blue"), ylim = range(0, Means, Means + SEs), ylab = "TcCB (ppb)", main = "Dynamite Plot for TcCB Data") errorBar(x = as.vector(group.centers), y = Means, lower = SEs, draw.lower = FALSE, gap = FALSE, col = c("red", "blue"), add = TRUE) # Confidence Interval Plot #------------------------- xlim <- par("usr")[1:2] dev.new() errorBar(x = as.vector(group.centers), y = Means, lower = LCLs, upper = UCLs, incr = FALSE, gap = FALSE, col = c("red", "blue"), xlim = xlim, xaxt = "n", xlab = "", ylab = "TcCB (ppb)", main = "Confidence Interval Plot for TcCB Data") axis(1, at = group.centers, labels = dimnames(TcCB.mat)[]) # Clean up #--------- rm(TcCB.mat, Means, SEs, LCLs, UCLs, group.centers, xlim) graphics.off() ```

### Example output

```Attaching package: 'EnvStats'

The following objects are masked from 'package:stats':

predict, predict.lm

The following object is masked from 'package:base':

print.default

dev.new(): using pdf(file="Rplots1.pdf")
```

EnvStats documentation built on Oct. 23, 2020, 6:41 p.m.