errorBar {EnvStats}

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 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 (NAs) 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 ([e-mail])

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