chplot                package:chplot                R Documentation

_A_u_g_m_e_n_t_e_d _C_o_n_v_e_x _H_u_l_l _P_l_o_t

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

     Plots 2D convex hulls or bivariate density contours, one for each
     group of data. Descriptive statistics are plotted as error bars or
     confidence ellipses within convex hulls. Marginal distributions as
     well as a special legend are added by default. Additionally, area
     of convex hull per point can be displayed.

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

     chplot(formula,data,chull=TRUE,clevel=0.95,band.power=.2,
     mar.den=FALSE,descriptives="mean.sd",dlevel=0.68,bw=FALSE,ratio=.75,
     plot.points=FALSE,log="",xlab,ylab,col,lty,legend,...)

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

 formula: a formula describing the form of conditioning plot. The
          formula is generally of the form 'y ~ x | g1', indicating
          that plots of 'y' (on the y axis) versus 'x' (on the x axis)
          should be produced conditional on the variable 'g1'. However,
          the conditioning variable 'g1' may be omitted. The names of
          the 'y', 'x' and 'g1' variables are used for the axes and
          legend title. 

    data: a data frame containing values for any variables in the
          formula. 

   chull: logical; if 'TRUE' (default), convex hulls are plotted,
          otherwise density contours are drawn. 

  clevel: the confidence level for the density plot if 'chull=FALSE'
          (default is 0.95). 

band.power: applies if 'chull=FALSE'; bandwidth for bivariate density
          estimation is calculated as '(group size)^(-band.power)' for
          each group (default is 0.2). 

 mar.den: logical; defines the type of marginal distribution plots. If
          'FALSE' (default), relative frequency polygons are plotted,
          otherwise density plots are drawn. 

descriptives: the option to be used for depicting descriptive
          statistics. The default value is 'mean.sd', which produces a
          cross with the lines intersecting at the mean of 'x' and 'y'
          for each group and depicting the 68-percent tolerance
          interval (i.e., stretching one standard deviation in each
          direction) with default 'dlevel' setting. Option 'mean.se'
          does the same with standard errors of the means, while
          'median' makes the lines one quartile long in each direction
          and cross at the median. Option 'ellipse' plots confidence
          ellipses. 

  dlevel: the tolerance/confidence level applied if
          'descriptives=mean.sd' or 'mean.se'. 

      bw: logical; if 'TRUE', the plot is produced in black-and-white.
          The default is 'FALSE', which plots in colour. 

   ratio: the ratio of the main plot to the whole figure region. The
          default value is 0.75. If equal to 1, the marginal
          distributions are not plotted. If the ratio is less or equal
          to 0.75, the default legend position is outside the main plot
          (i.e., in the top right corner), otherwise it is within the
          main plot (i.e., to be selected by the user with mouse). 

plot.points: are the points added to the original plot? Default is
          'FALSE'.

     log: the character strings '"x"', '"y"' or '"xy"' makes a specific
          (or both) axes logarithmic; the default, which does nothing,
          is '""'. 

    xlab: a title for the x axis in the main plot; the default is the
          name of the x variable. 

    ylab: a title for the y axis in the main plot; the default is the
          name of the y variable. 

     col: the plotting colors; vector of length equalling the number of
          groups.

     lty: the type of line; vector of length equalling the number of
          groups.

  legend: either logical, in which case the default is 'TRUE' and a
          legend is drawn with the default settings, or a list of
          legend parameters. For legend parameters, see the 'legend'
          function; two additional parameters are allowed: 'area.in'
          (logical; specifies whether the area of convex hull per point
          is displayed; default is 'TRUE' if 'chull=TRUE' and 'FALSE'
          otherwise), and 'pos' ('in' or 'out'; default depends on
          'ratio' value; if 'in' is chosen, the legend is positioned by
          the user with mouse, while 'out' places the legend in the top
          right corner of the plotting area). Note that the default
          legend parameters are not the same as in the 'legend'
          function: default 'title' is the name of the grouping
          variable, default 'bty' depends on legend position ('"o"' if
          inside and '"n"' if outside), while default 'cex' is
          calculated on the basis of 'ratio', and the 'cex' option is
          the multiplier of that default. 

     ...: other arguments will be passed to the main plotting region
          and will affect points if 'plot.points=TRUE'.

_D_e_t_a_i_l_s:

     The relative frequency polygons chosen with 'mar.den=FALSE'
     connect the points in the middle of the intervals and the starting
     and ending interval with zero frequency in each group. All the
     frequencies are rescaled in order to make the plots immediately
     comparable (the same is true for the density curves).

     The default density contour might not fit into the plot - this can
     be avoided by decreasing the 'clevel'. In case of broken contours,
     the area per point is not a sensible measure.

_V_a_l_u_e:

     A list with components: 

    area: the area of convex hull per point for each group.

    usrc: the limits of the central plotting region.

    usru: the limits of the top left plotting region.

    usrr: the limits of the bottom right plotting region.

   ratio: the ratio used.

 is.xlog: logical, denoting whether either 'log="x"' or  'log="xy"' was
          used.

 is.ylog: logical, denoting whether either 'log="y"' or  'log="xy"' was
          used.

_R_e_f_e_r_e_n_c_e_s:

     Vidmar, G., and Pohar, M. Augmented convex hull plots: rationale,
     implementation in R and biomedical applications. _Computer Methods
     and Programs in Biomedicine_, 2005, 78, 69-74.

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

     'chadd', 'chull', 'bkde2D'.

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

     # the hdr dataset
     data(hdr)
     chplot(age~income|gender,data=hdr,log="x")
     # the iris dataset
     data(iris)
     chplot(Sepal.Length~Sepal.Width|Species,data=iris,bw=TRUE,
            legend=list(cex=.6))
     chplot(Petal.Length ~ Petal.Width | Species, data = iris,
           legend = list(cex = 0.6),plot.points=TRUE,pch = 18, cex = 0.5)

