chplot {chplot}R Documentation

Augmented Convex Hull Plot

Description

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.

Usage

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,lwd,legend=TRUE,...)

Arguments

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.
lwd line width; 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.

Details

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.

Value

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.

References

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.

See Also

chadd, chull, bkde2D.

Examples

# the hdr dataset
postscript("file.ps",fonts="mono")         # For screen output, skip this
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)
dev.off()               # For screen output, skip this

[Package chplot version 1.3.1 Index]