boxplotdou: Double Box Plot

Description

Extend box plot chart into two-axes (x and y) to visualize correlation.

Usage

boxplotdou(x, ...)
# S3 method for default
boxplotdou(x, y, 
           boxed.whiskers=FALSE, outliers.has.whiskers=FALSE, 
           name.on.axis=factor.labels, factor.labels=NULL, draw.legend=NA,
           condense=FALSE, condense.severity="iqr",
           condense.once=FALSE,
           col=NULL,
           COLOR.SHEER=bxpdou.sheer.color, 
           shading=NA, shading.angle=NA, blackwhite=FALSE,
           STAT=bxpdou.boxplot.stat, 
           verbose=FALSE, plot=TRUE, ...) 
# S3 method for data.frame
boxplotdou(x, y, 
           boxed.whiskers=FALSE, outliers.has.whiskers=FALSE, 
           name.on.axis=factor.labels, factor.labels=NULL, draw.legend=NA,
           condense=FALSE, condense.severity="iqr",
           condense.once=FALSE,
           col=NULL,
           COLOR.SHEER=bxpdou.sheer.color, 
           shading=NA, shading.angle=NA, blackwhite=FALSE,
           STAT=bxpdou.boxplot.stat, 
           verbose=FALSE, plot=TRUE, ...) 
# S3 method for factor
boxplotdou(x, obs.x, f.y, obs.y,  
           boxed.whiskers=FALSE, outliers.has.whiskers=FALSE, 
           name.on.axis=factor.labels, factor.labels=NULL, draw.legend=NA,
           condense=FALSE, condense.severity="iqr",
           condense.once=FALSE,
           col=NULL,
           COLOR.SHEER=bxpdou.sheer.color, 
           shading=NA, shading.angle=NA, blackwhite=FALSE,
           STAT=bxpdou.boxplot.stat, 
           verbose=FALSE, plot=TRUE, ...) 
# S3 method for formula
boxplotdou(formula.x, data.x, formula.y, data.y,  
           boxed.whiskers=FALSE, outliers.has.whiskers=FALSE, 
           name.on.axis=factor.labels, factor.labels=NULL, draw.legend=NA,
           condense=FALSE, condense.severity="iqr",
           condense.once=FALSE,
           col=NULL,
           COLOR.SHEER=bxpdou.sheer.color, 
           shading=NA, shading.angle=NA, blackwhite=FALSE,
           STAT=bxpdou.boxplot.stat, 
           verbose=FALSE, plot=TRUE, ...) 
# S3 method for list
boxplotdou(x, 
           boxed.whiskers=FALSE, outliers.has.whiskers=FALSE, 
           name.on.axis=factor.labels, factor.labels=NULL, draw.legend=NA,
           col=NULL,
           COLOR.SHEER=bxpdou.sheer.color, 
           shading=NA, shading.angle=NA, blackwhite=FALSE,
           verbose=FALSE, plot=TRUE, ...)

Arguments

data frame, contains two columns as factor and observation to x-axis (for boxplotdou.default, that is, = boxplotdou.data.frame). factor vector, as factor to x-axis (for boxplotdou.factor). list, output values of boxplotdou, eg. previously saved stat to redraw a chart, (for boxplotdou.list).

data frame, contains two columns as factor and observation to y-axis (for boxplotdou.default, that is, = boxplotdou.data.frame).

obs.x

numeric vector, as observation to x-axis (for boxplotdou.factor).

f.y

factor vector, as factor to y-axis (for boxplotdou.factor).

obs.y

numeric vector, as observation to y-axis (for boxplotdou.factor).

formula.x

formula, a model formula to x-axis, eg. obs ~ factor (for boxplotdou.formula).

data.x

data.frame, contains variables in formula.x (for boxplotdou.formula).

formula.y

formula, a model formula to y-axis, eg. obs ~ factor (for boxplotdou.formula).

data.y

data.frame, contains variables in formula.y (for boxplotdou.formula).

boxed.whiskers

logical, default is FALSE, TRUE to draw rectangular range rather than whisker and staple.

outliers.has.whiskers

logical, default is FALSE, extend whisker and staple through outliers.

name.on.axis

control labels on each group on axes, default is factor.labels, NULL to use factor data, TRUE to abbreviate by alphabet letters, FALSE to draw no labels, character vector to give explicit labels, single character to use identical character.

factor.labels

control labels on each group on factor, default is NULL, using factor data, TRUE to abbreviate by alphabet letters, FALSE to draw no labels, character vector to give explicit labels, single character to use identical character, NA in vector to exclude any groups.

draw.legend

logical, draw legend or not, default is NA, enable legend only when labels abbreviated.

condense

logical, default is FALSE, TRUE to unify near groups into one box.

condense.severity

character, default is "iqr", one of c('iqr','whisker','iqr.xory','whisker.xory'), which is the border to condense or not, used only when condense=TRUE.

condense.once

logical, default is FALSE, TRUE to disable recursive condenses, used only when condense=TRUE.

col

character vector, colors for each group, default is NULL, automatic colors.

COLOR.SHEER

function, to convert color to sheer color, default is bxpdou.sheer.color, internally defined as, function(col) adjustcolor(col, alpha.f=0.2). sheer colors are used for inside box, or for outliers.has.whiskers=TRUE.

shading

numeric vector, as shading density to draw inside of box. default is NA, means automatic, no shadings when both shading and shading.angle are NA. the density value means lines per inch. the generator depends the vector length.

1: a sigle value is used to all densities
2: values are generated between the pair
k: when k is number of factor levels, values are used to each level

logical value TRUE has a special meaning to enable shading with automatic densities.

shading.angle

numeric vector, as shading angle to draw inside of box. default is NA, means automatic, no shadings when both shading and shading.angle are NA. the angle value means degree of line direction to horizon. the generator depends the vector length with same manner of density.

blackwhite

logical, default is FALSE, TRUE to draw black and white chart, equivalent to set following 3 parameters, col='black', shading=TRUE, COLOR.SHEER=(function(a) a)

STAT

function, default is bxpdou.boxplot.stat, internally defined as, function(formula) boxplot(formula=formula, plot=FALSE), delegates to standard boxplot function. specify user function to calculate summary.

plot

if FALSE is given, it disable to plot and print a summary. default is TRUE.

verbose

if TRUE is given, it print verbose debugging information. default is FALSE.

…

plot parameters and boxplot color parameters are acceptable.

Value

A summary list is explicitly printed when plot=FALSE is given, and is invisibly returned when plot=TRUE.

stat

x: x-axis summary, same as boxplot statistics
y: y-axis summary, same as boxplot statistics

name

x: character, x-axis label
y: character, y-axis label

level

character vecotr of factor names

Each summary of x and y is identical to boxplot statistics,

stats

matrix, each column contains the extreme of the lower whisker, the lower hinge, the median, the upper hinge and the extreme of the upper whisker.

numerical vector, sample numbers of each factor level.

conf

matrix, each column contains the lower and upper extremes of the notch.

out

numerical vector, outliers

group

numerical vector of same length as out, indicates which factor level the outlier belongs.

names

character vector, each name of factor levels.

boxplot color parameters

medcol: default is NULL, to use black, colors for median labels.
whiskcol: default is NULL, to use col, colors for whiskers.
staplecol: default is NULL, to use col, colors for staples.
boxcol: default is NULL, to use black, colors for box borders.
outcol: default is NULL, to use col, colors for outliers.
outbg: default is NULL, to use transparent, colors inside outliers.
outcex: default is 2, size of outliers.
outpch: default is 1, to use a transparent circle, symbol number of outliers, as graphic par pch.

Details

This function is designed to visualize a correlation between 2 sets of independent observation with common factors. Such as, the plant height v.s. the soil pH by location. This function depends on boxplot function to calculate summaries such as IQRs. This dependency can be overridden by STAT argument.

References

Double Box Plot: https://tomizonor.wordpress.com/2013/03/15/double-box-plot/ Double Box Plot 1.2: https://tomizonor.wordpress.com/2013/11/24/double-box-plot-1-2/

Examples

Run this code

# NOT RUN {
# iris data: Sepal.Length v.s. Sepal.Width by Species
stat <- boxplotdou(iris[c(5,1)], iris[c(5,2)])
boxplotdou(iris[,5], iris[,1], iris[,5], iris[,2])
boxplotdou(Sepal.Length~Species, iris, Sepal.Width~Species, iris)
boxplotdou(stat, main='redraw by saved stat')

# color and shading
boxplotdou(iris[c(5,1)], iris[c(5,2)], col=c('wheat','wheat','black'),
           boxcol='springgreen')
boxplotdou(iris[c(5,1)], iris[c(5,2)], shading=c(3,5))
boxplotdou(iris[c(5,1)], iris[c(5,2)], shading=5, shading.angle=c(0,90))
boxplotdou(iris[c(5,1)], iris[c(5,2)], blackwhite=TRUE)

# customized sheer funtion
mysheer <- function(x) 
             adjustcolor(x, alpha.f=0.2, red.f=0.3, green.f=0.3, blue.f=0.3)
boxplotdou(iris[c(5,1)], iris[c(5,2)], COLOR.SHEER=mysheer)

# whisker
boxplotdou(iris[c(5,1)], iris[c(5,2)], boxed.whiskers=TRUE)
boxplotdou(iris[c(5,1)], iris[c(5,2)], outliers.has.whiskers=TRUE)

# condense
boxplotdou(iris[c(5,1)], iris[c(5,2)], condense=TRUE)

# labels
boxplotdou(iris[c(5,1)], iris[c(5,2)], factor.labels=FALSE)
boxplotdou(iris[c(5,1)], iris[c(5,2)], factor.labels=TRUE)
boxplotdou(iris[c(5,1)], iris[c(5,2)], factor.labels=TRUE, 
                                       draw.legend=FALSE)
boxplotdou(iris[c(5,1)], iris[c(5,2)], factor.labels=c('Se','Ve','Vi'))
boxplotdou(iris[c(5,1)], iris[c(5,2)], factor.labels='+', 
                                       name.on.axis=FALSE)

# customized summary function
mystat <- function(x) boxplot(formula=x, range=1, plot=FALSE)
boxplotdou(iris[c(5,1)], iris[c(5,2)], STAT=mystat)

# graphic parameters
boxplotdou(iris[c(5,1)], iris[c(5,2)], xlim=c(4.8, 7.0), ylim=c(2.0, 3.5))

# print summary
boxplotdou(iris[c(5,1)], iris[c(5,2)], plot=FALSE)
# }

Run the code above in your browser using DataLab