EnvStats (version 2.1.0)

errorBar: Plot Pointwise Error Bars

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

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 specifi

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

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

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 th

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

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).

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).

Details

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

References

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

See Also

plot, segments, pointwise, stripChart.

Examples

# 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)[[1]])


  # Clean up
  #---------
  rm(TcCB.mat, Means, SEs, LCLs, UCLs, group.centers, xlim)
  graphics.off()