bxp                 package:graphics                 R Documentation

_D_r_a_w _B_o_x _P_l_o_t_s _f_r_o_m _S_u_m_m_a_r_i_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     'bxp' draws box plots based on the given summaries in 'z'. It is
     usually called from within 'boxplot', but can be invoked directly.

_U_s_a_g_e:

     bxp(z, notch = FALSE, width = NULL, varwidth = FALSE,
         outline = TRUE, notch.frac = 0.5, log = "",
         border = par("fg"), pars = NULL, frame.plot = axes,
         horizontal = FALSE, add = FALSE, at = NULL, show.names = NULL,
         ...)

_A_r_g_u_m_e_n_t_s:

       z: a list containing data summaries to be used in constructing
          the plots.  These are usually the result of a call to
          'boxplot', but can be generated in any fashion.

   notch: if 'notch' is 'TRUE', a notch is drawn in each side of the
          boxes.  If the notches of two plots do not overlap then the
          medians are significantly different at the 5 percent level.

   width: a vector giving the relative widths of the boxes making up
          the plot.

varwidth: if 'varwidth' is 'TRUE', the boxes are drawn with widths
          proportional to the square-roots of the number of
          observations in the groups.

 outline: if 'outline' is not true, the outliers are not drawn.

notch.frac: numeric in (0,1). When 'notch=TRUE', the fraction of the
          box width that the notches should use.

  border: character or numeric (vector), the color of the box borders. 
          Is recycled for multiple boxes.  Is used as default for the
          'boxcol', 'medcol', 'whiskcol', 'staplecol', and 'outcol'
          options (see below). 

     log: character, indicating if any axis should be drawn in
          logarithmic scale, as in 'plot.default'.

frame.plot: logical, indicating if a 'frame' ('box') should be drawn;
          defaults to 'TRUE', unless 'axes = FALSE' is specified.

horizontal: logical indicating if the  boxplots should be horizontal;
          default 'FALSE' means vertical boxes.

     add: logical, if true _add_ boxplot to current plot.

      at: numeric vector giving the locations where the boxplots should
          be drawn, particularly when 'add = TRUE'; defaults to '1:n'
          where 'n' is the number of boxes.

show.names: Set to 'TRUE' or 'FALSE' to override the defaults on
          whether an x-axis label is printed for each group.

pars,...: graphical parameters (etc) can be passed as arguments to this
          function, either as a list ('pars') or normally('...'), see
          the following.  (Those in '...' take precedence over those in
          'pars'.)

          Currently, 'yaxs' and 'ylim' are used 'along the boxplot',
          i.e., vertically, when 'horizontal' is false, and 'xlim'
          horizontally. 'xaxt', 'yaxt', 'las', 'cex.axis', and
          'col.axis' are passed to 'axis', and 'main', 'cex.main',
          'col.main', 'sub', 'cex.sub', 'col.sub', 'xlab', 'ylab',
          'cex.lab', and 'col.lab' are passed to 'title'.

          In addition, 'axes' is accepted (see 'plot.window'), with
          default 'TRUE'.

          The following arguments (or 'pars' components) allow further
          customization of the boxplot graphics.  Their defaults are
          typically determined from the non-prefixed version (e.g.,
          'boxlty' from 'lty'), either from the specified argument or
          'pars' component or the corresponding 'par' one.

          _b_o_x_w_e_x: a scale factor to be applied to all boxes.  When
               there are only a few groups, the appearance of the plot
               can be improved by making the boxes narrower.  The
               default depends on 'at' and typically is 0.8.

          _s_t_a_p_l_e_w_e_x, _o_u_t_w_e_x: staple and outlier line width expansion,
               proportional to box width; both default to 0.5.

          _b_o_x_l_t_y, _b_o_x_l_w_d, _b_o_x_c_o_l, _b_o_x_f_i_l_l: box outline type, width,
               color, and fill color (which currently defaults to 'col'
               and will in future default to 'par("bg")').

          _m_e_d_l_t_y, _m_e_d_l_w_d, _m_e_d_p_c_h, _m_e_d_c_e_x, _m_e_d_c_o_l, _m_e_d_b_g: median line
               type, line width, point character, point size expansion,
               color, and background color.  The default 'medpch= NA'
               suppresses the point, and 'medlty="blank"' does so for
               the line. Note that'medlwd' defaults to 3x the default
               'lwd'.

          _w_h_i_s_k_l_t_y, _w_h_i_s_k_l_w_d, _w_h_i_s_k_c_o_l: whisker line type (default:
               '"dashed"'), width, and color.

          _s_t_a_p_l_e_l_t_y, _s_t_a_p_l_e_l_w_d, _s_t_a_p_l_e_c_o_l: staple (= end of whisker)
               line type, width, and color.

          _o_u_t_l_t_y, _o_u_t_l_w_d, _o_u_t_p_c_h, _o_u_t_c_e_x, _o_u_t_c_o_l, _o_u_t_b_g: outlier line
               type, line width, point character, point size expansion,
               color, and background color.  The default 'outlty=
               "blank"' suppresses the lines and 'outpch=NA' suppresses
               points.

_V_a_l_u_e:

     An invisible vector, actually identical to the 'at' argument, with
     the coordinates ("x" if horizontal is false, "y" otherwise) of box
     centers, useful for adding to the plot.

_N_o_t_e:

     if 'add = FALSE', the default is 'xlim = c(0.5, n +0.5)'. It will
     usually be a good idea to specify the latter if the "x" axis has a
     log scale or 'at' is specified or 'width' is far from uniform.

_A_u_t_h_o_r(_s):

     The R Core development team and Arni Magnusson
     arnima@u.washington.edu who has provided most changes for the
     box*, med*, whisk*, staple*, and out* arguments.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

_E_x_a_m_p_l_e_s:

     require(stats)
     set.seed(753)
     (bx.p <- boxplot(split(rt(100, 4), gl(5,20))))
     op <- par(mfrow= c(2,2))
     bxp(bx.p, xaxt = "n")
     bxp(bx.p, notch = TRUE, axes = FALSE, pch = 4, boxfill=1:5)
     bxp(bx.p, notch = TRUE, boxfill= "lightblue", frame= FALSE,
         outl= FALSE, main = "bxp(*, frame= FALSE, outl= FALSE)")
     bxp(bx.p, notch = TRUE, boxfill= "lightblue", border= 2:6,
         ylim = c(-4,4), pch = 22, bg = "green", log = "x",
         main = "... log='x', ylim=*")
     par(op)
     op <- par(mfrow= c(1,2))

     ## single group -- no label
     boxplot (weight ~ group, data = PlantGrowth, subset = group=="ctrl")
     ## with label
     bx <- boxplot(weight ~ group, data = PlantGrowth,
                   subset = group=="ctrl", plot = FALSE)
     bxp(bx,show.names=TRUE)
     par(op)

     z <- split(rnorm(1000), rpois(1000,2.2))
     boxplot(z, whisklty=3, main="boxplot(z, whisklty = 3)")

     ## Colour support similar to plot.default:
     op <- par(mfrow=1:2, bg="light gray", fg="midnight blue")
     boxplot(z,   col.axis="skyblue3", main="boxplot(*, col.axis=..,main=..)")
     plot(z[[1]], col.axis="skyblue3", main=   "plot(*, col.axis=..,main=..)")
     mtext("par(bg=\"light gray\", fg=\"midnight blue\")",
           outer = TRUE, line = -1.2)
     par(op)

     ## Mimic S-Plus:
     splus <- list(boxwex=0.4, staplewex=1, outwex=1, boxfill="grey40",
                   medlwd=3, medcol="white", whisklty=3, outlty=1, outpch=NA)
     boxplot(z, pars=splus)
     ## Recycled and "sweeping" parameters
     op <- par(mfrow=c(1,2))
      boxplot(z, border=1:5, lty = 3, medlty = 1, medlwd = 2.5)
      boxplot(z, boxfill=1:3, pch=1:5, lwd = 1.5, medcol="white")
     par(op)
     ## too many possibilities
     boxplot(z, boxfill= "light gray", outpch = 21:25, outlty = 2,
             bg = "pink", lwd = 2,
             medcol = "dark blue", medcex = 2, medpch = 20)