plotCI                package:gplots                R Documentation

_P_l_o_t _E_r_r_o_r _B_a_r_s _a_n_d _C_o_n_f_i_d_e_n_c_e _I_n_t_e_r_v_a_l_s

_D_e_s_c_r_i_p_t_i_o_n:

     Given a set of x and y values and interval width or upper and
     lower bounds, plot the points with error bars.  This can be a
     useful tool for visualizing confidence intervals.

_U_s_a_g_e:

     plotCI(x, y = NULL, uiw, liw = uiw, ui, li, err='y', ylim=NULL,
            xlim=NULL, type="p",  col=par("col"), barcol=col,
            pt.bg = par("bg"),  sfrac = 0.01, gap=1, lwd=par("lwd"),
            lty=par("lty"), labels=FALSE, add=FALSE, xlab, ylab,  minbar,
            maxbar, ... )

_A_r_g_u_m_e_n_t_s:

     x,y: coordinates for the center of error bars. 'y' defaults to
          '1:n'.

     uiw: width of the upper or right error bar. Set to 'NULL' omit
          upper bars.

     liw: width of the lower or left error bar.  Defaults to same value
          as 'uiw'.  Set to 'NULL' to omit lower bars. 

      ui: upper end of error bars.  Defaults to 'y + uiw' or 'x + uiw'
          depeding on 'err'.  Set to 'NULL' omit upper bars. 

      li: lower end of error bars.  Defaults to 'y - liw' or 'x - liw'
          depedning on 'err'.  Set to 'NULL' to omit lower bars.

     err: direction for error bars. Set to "y" for vertical bars. Set
          to "x" for horizontal bars. Defaults to "y".

     col: color of plotting character used center marker of error bars.
          Default is "black".

xlim, ylim: range of x/y values to include in the plotting area. 

    type: point/line type; passed to 'points'

  barcol: color of the error bars.  Defaults to the same value as 'col' 

   pt.bg: background color of points (use 'pch=21, pt.bg=par("bg")' to
          get open points superimposed on error bars).

   sfrac: width of "crossbar" at the end of error bar as a fraction of
          the x plotting region. Defaults to 0.01. 

     gap: space left between the center of the error bar and the lines
          marking the error bar in units of the height (width) of the
          letter "O".  Defaults to 1.0 

     lwd: width of bar lines. 

     lty: line type of bar lines. 

  labels: either a logical value indicating whether the circles
          representing the x values should be replaced with text giving
          the actual values or a vector containing labels to use
          instead. Defaults to 'FALSE'. 

     add: logical indicating whether error bars should be added to the
          current plot.  If 'FALSE' (the defailt), a new plot will be
          created and symbols/labels for the x values will be plotted
          before drawing error bars.

  minbar: minumum allowed value for bar ends.  If specified, values
          smaller than 'minbar' will be replaced with 'minbar'. 

  maxbar: maximum allowed value for bar ends.  If specified, values
          larger than 'maxbar' will be replaced with 'maxbar'. 

     ...: optional plotting parameters 

    xlab: label for x axis. 

    ylab: label for y axis. 

_A_u_t_h_o_r(_s):

     Original version by Bill Venables
     wvenable@attunga.stats.adelaide.edu.au posted to r-help on Sep.
     20, 1997.  Enhanced version posted to r-help by Ben Bolker
     ben@zoo.ufl.edu on Apr. 16, 2001.  This version was modified and
     extended by Gregory R. Warnes warnes@bst.rochester.edu. 
     Additional changes suggested by Martin Maechler
     maechler@stat.math.ethz.ch integrated on July 29, 2004.

_S_e_e _A_l_s_o:

     'plotmeans' provides an enhanced wrapper to 'plotCI'.

_E_x_a_m_p_l_e_s:

       # plot means and
       data(state)
       tmp   <- split(state.area, state.region)
       means <- sapply(tmp, mean)
       stdev <- sqrt(sapply(tmp, var))
       n     <- sapply(tmp,length)
       ciw   <- qt(0.975, n) * stdev / sqrt(n)

       # plain
       plotCI(x=means, uiw=ciw)

       # prettier
       plotCI(x=means, uiw=ciw, col="black", barcol="blue", lwd=1)

       # give mean values
       plotCI(x=means, uiw=ciw, col="black", barcol="blue",
              labels=round(means,-3), xaxt="n", xlim=c(0,5) )
       axis(side=1, at=1:4, labels=names(tmp), cex=0.7)

       # better yet, just use plotmeans ... #
       plotmeans( state.area ~ state.region )

