BoxPlot: Box/Box-Percentile Plot with additional vertical stripchart,...

In lengning/gClinBiomarker: gClinBiomarker: an R package for clinical biomarker analyses

Description

This function produces boxplots as function boxplot and box-percentile plots as function bpplot (package Hmisc), offering a formula interface, data specification via a vector of variable names, as numeric matrix where all columns will be interpreted as variables or by specifying one or multiple numeric vectors (see examples below). It additionally/optionally adds vertical jitterplots to each boxplot, adds the number of observations, adds mean-values, and allows to add a trend-line connecting either mean-values (trend="mean") or median-values (trend="median"). Furthermore, this function filters for groups with less than 'threshold' observations. For these (sub-)groups no boxplots will be drawn but a jitterplot will be produced. Labels for each group (X-axis labels) can be customized via 'xlab.srt', 'xlab.cex', 'xlab.col', 'xlab.font'. Note: When using the formula-interface, one cannot specify formulas as in function 'boxplot' i.e. using something like 'a + b' to get factor crossing, one has to use the correct formula instead as used in e.g. 'lm', i.e. 'a:b'.

Usage

BoxPlot(..., obj, form = NULL, var = NULL, box.type = "b",
  horizontal = FALSE, col = "white", sc.col = "#00000040", sc.pch = 15L,
  sc.cex = 1, sc.jitter = 0.1, Xaxis = list(side = 1, mgp = c(3, 0.5, 0),
  font = 1, tick = TRUE), Xaxis2 = list(side = 3, font = 2, mgp = c(3, 0.5,
  0), tick = TRUE), XaxisTab = NULL, Yaxis = list(side = 2, mgp = c(3, 1,
  0)), Ylabel = list(text = "", side = 2, line = 2.5, font = 1, cex = 1),
  Xlabel = list(text = "", side = 1, line = 2.5, font = 1, cex = 1),
  Title = list(line = 2.5), Grid = NULL, transf = NULL, trend = NULL,
  trend.lty = 1L, trend.lwd = 1, trend.col = "blue", threshold = 5L,
  border = "black", mean.pch = 3L, mean.cex = 1.5, mean.col = "salmon",
  mean.lwd = 2L, vline = NULL, vl.lwd = 1L, vl.lty = 1L,
  vl.col = "black", Box = TRUE)

Arguments

...	a numeric matrix, multiple numeric vectors or a (possibly named) list with multiple numeric vectors to be plotted and additional graphical parameters (identified by names) to be passed on.
obj	(data.frame, matrix) corresponding to the dataset to be used.
form	(formula) such as 'y~grp', where 'y' is a numeric vector of data values to be split into groups according to the grouping variable 'grp'.
var	(character) vector specifying the columns in 'obj' to be used for plotting. The order of elements is retained in the boxplot.
box.type	(character) "b" = for regular boxes, "bp" = for box-percentile boxes (see ? bpplot of package Hmisc).
horizontal	(logical) TRUE = the boxes are drawn horizontally, FALSE = vertical boxplot. Note, this has no effect when box.type="bp", since the underlying function bpplot of the Hmisc package cannot do it. Also note, that horizontal=TRUE automatically changes the meaning of X- and Y-axis. All arguments referring to Y-axis will then implicitely mean the X-axis and vice versa.
col	(character) string(s) specifying colors to be used to color the bodies of the box plots. By default they are in the background color.
sc.col	(character) string or vector of strings specifying color(s) of plotting symbols in the stripchart. By default "black" with 80% transparency (alpha=.2). In case of a vector of strings, it is best practise to provide as many elements as there are elements in 'obj', which can be used to highlight an additional grouping factor within a single box. Note, it is the responsibility of the user to provide 'sc.col', 'sc.pch' or 'sc.cex' in such a way, that the graphical output is meaningful. In case of providing less than 'nrow(obj)' elements, 'sc.col' will be replicated to the required length.
sc.pch	(integer) value or vector of integers specifying plotting smybols for the stripchart. The same rules as for 'sc.col' and 'sc.cex' apply here.
sc.cex	(numeric) value or vector of numeric values specifying the magnification of plotting symbols in the stripchart. The same rules as for 'sc.col' and 'sc.cex' apply here.
sc.jitter	(numeric) specifying the amount of jittering in the stripchart.
Xaxis	(list) passed to function 'axis' which allows to fully specify the X-axis labelling (see ?axis). Default is to determine group labels automatically and plotting group labels below the plot. Set to NULL for omitting group labels. For custom group-labels use the list-element "labels". The order of these labels must correspond to the order of group-levels in case the formula interface was used, i.e. check the order of sort(unique(obj$grp)). To obtain your desired ordering, specify classification variables as factor-objects using 'factor(dat$trt, levels=c("Level_1", "Level_2", ..., "Level_n"))' where "trt" is the classification variable and Level_1 to Level_n represents your desired order of factor levels (which is used in the plot).
Xaxis2	(list) passed to function 'axis' which allows to fully specify the X-axis labelling above the plot (see ?axis). This is used to specify the number of observations per sub-group according to the group-labels. Default is to plot these numbers above the plot. To omit set to NULL. Note, if 'horizontal=TRUE' this axis-labelling will appear in the right margin and labels will be oriented perpendicular to the axis. Set 'Xaxis2=list(las=0)' to overwrite the default for usual parallel orientation.
XaxisTab	(list) or NULL, if a (possibly empty) list AND 'form' is specified, 'Xaxis' will be set to NULL and a table will be used a X-axis label representing the combination of factor-levels for all factors appearing in 'form' (see example document and see addXlabTable). If 'horizontal=TRUE' the table will appear in the left margin as any other setting originally intended to apply to an X-axis element. Note, there has to be enough space in the bottom margin for adding the table (use "mai" or "mar" in par). Your may specify 'XaxisTab' as list with two sub-lists "Label" and "Text", which will then be evaluated for rownames of the table ("Label") and the text in the cells of the table ("Text") separately (see examples of function addXlabTable for details).
Yaxis	(list) passed to function 'axis' which allows to fully specify the the appearence of the Y-axis (see ?axis).
Ylabel	(list) passed to function 'mtext' which can be used to fully specify the Y-axis label.
Xlabel	(list) passed to function 'mtext' which can be used to fully specify the X-axis label or even group labels (see example document).
Title	(list) passed to function 'title'.
Grid	(list) passed to function 'grid'. Set to NULL to omit (default). For adding a grid simply set 'Grid=TRUE' which applies default settings for the added grid or fully specify the grid to be added by specifying each argument (see ?addGrid for details).
transf	(function) name of a function to be used to tranform data before plotting, e.g. log, log10 or user-defined functions, i.e. func=function(x)x[x==0]<-min(x, na.rm=TRUE)/2 and setting 'transf=func'.
trend	(character) "mean" = mean values are connected by a line emphasizing the dynamics (especially for time course data) "median" = median values are used, set to NULL to omit.
trend.lty	(integer) line type of the trend line.
trend.lwd	(numeric) line width of the trend line.
trend.col	(character) color of the trend line.
threshold	(integer) minimum number of points required for plotting a boxplot, otherwise only the stripchart will be plotted.
border	(character) string specifying the border color(s) of boxes. This can be a vector with different colors for multiple boxes.
mean.pch	(integer) plotting symbol for mean-values, which are added to the plot. Use '-1' to prevent plotting of mean-values.
mean.cex	(numeric) specifying the magnification of mean-value plotting symbols.
mean.col	(character) specifying the color of mean-value plotting symbols.
mean.lwd	(integer) specifying the line width of mean-value plotting symbols (cross, plus, asterisk etc.).
vline	(numeric) value(s) specifying vertical lines added to the plot.
vl.lwd	(integer) line width of vertical lines.
vl.lty	(integer) line type of vertical lines.
vl.col	(character) color of vertical lines.
Box	(logical) TRUE = a box is plotted surrounding the plot, FALSE = no box.

Author(s)

Andre Schuetzenmeister [e-mail], Vinzent Rolny [e-mail], christina Rabe [e-mail]

Examples

data(input)

## specify variables to plot
BoxPlot(input, KRAS.exprs~Arm, transf = log)

## same plot, now horizontally plotted
BoxPlot(input, KRAS.exprs~Arm, transf = log, horizontal=TRUE,
       Xaxis=list(las=2, hadj=2), Xaxis2=list(las=2, hadj=-.25))

lengning/gClinBiomarker documentation built on May 9, 2019, 2:55 p.m.