varPlot: Variability Chart for Hierarchical Models.

Description

Function varPlot determines the sequence of variables in the model formula and uses this information to construct the variability chart.

Usage

varPlot(form, Data, keep.order = TRUE, type = c(1L, 2L, 3L)[1],
  VARtype = "SD", htab = 0.5, Title = NULL, VSpace = NULL,
  VarLab = list(cex = 0.75, adj = c(0.5, 0.5)), YLabel = list(text =
  "Value", side = 2, line = 2.5), SDYLabel = list(side = 2, line = 2.5),
  Points = list(pch = 16, cex = 0.5, col = "black"), SDs = list(pch = 16,
  col = "blue", cex = 0.75), SDline = list(lwd = 1, lty = 1, col = "blue"),
  BG = list(border = "lightgray", col.table = FALSE), VLine = NULL,
  Join = list(lty = 1, lwd = 1, col = "gray"), JoinLevels = NULL,
  Mean = list(pch = 3, col = "red", cex = 0.5), MeanLine = NULL,
  VCnam = list(cex = 0.75, col = "black", line = 0.25), useVarNam = FALSE,
  ylim = NULL, max.level = 25, ...)

Arguments

form

(formula) object specifying the model, NOTE: any crossed factors are reduced to last term of the crossing structure, i.e. "a:b" is reduced to "b", "a:b:c" is reduced to "c".

Data

(data.frame) with the data

keep.order

(logical) TRUE = the ordering of factor-levels is kept as provided by 'Data', FALSE = factor-levels are sorted on and within each level of nesting.

type

(integer) specifying the type of plot to be used, options are 1 = regular scatterplot, 2 = plot of the standard deviation, 3 = both type of plots.

VARtype

(character) either "SD" (standard deviation) or "CV" (coefficient of variation), controls which type of measures is used to report variability in plots when 'type' is set to either 2 or (see 'type' above). Note that all parameters which apply to the SD

htab

(numeric) value 0 < htab < 1 specifying the height of the table representing the experimental design. This value represents the proportion in relation to the actual plotting area, i.e. htab=1 mean 50% of the vertical space is reserved for the table.

Title

(list) specifying all parameters applicable to function 'title' for printing main- or sub-titles to plots. If 'type==3', these settings will apply to each plot. For individual settings specify a list with two elements, where each element is a list it

VSpace

(numeric) vector of the same length as there are variance components, specifying the proportion of vertical space assigned to each variance component in the tabular indicating the model structure. These elements have to sum to 1, otherwise equal size

VarLab

(list) specifying all parameters applicable to function 'text', used to add labels within the table environment refering to the nesting structure. This can be a list of lists, where the i-th list corresponds to the i-th variance component, counted in bo

YLabel

(list) specifying all parameters applicable to function 'mtext', used for labelling the Y-axis.

SDYLabel

(list) specifying all parameters applicable to function 'mtext', used for labelling the Y-axis.

Points

(list) specifying all parameters applicable to function 'points', used to specify scatterplots per lower-end factor-level (e.g. 'run' in formula run/day). If list-elements "col" and "pch" are lists themselves with elements "var" and "col"/"pch", wher

SDs

(list) specifying all parameters applicable to function 'points', used to specify the appearance of SD-plots.

SDline

(list) specifying all parameters applicable to function 'lines', used to specify the (optional) line joining individual SDs, Set to NULL to omit.

(list) specifying the background for factor-levels of a nested factor. This list is passed on to function 'rect' after element 'var', which identifies the factor to be used for coloring, has been removed. If not set to NULL and no factor has been specifi

VLine

(list) specifying all parameters applicable in lines optionally separating levels of one or multiple variables as vertical lines. This is useful in addition to 'BG' (see examples), where automatically 'borde

Join

(list) specifying lines joining observed values within lower-level factor-levels, set to NULL to omit.

JoinLevels

(list) specifying all arguments applicable in function lines, joining factor-levels nested within higher order factor levels, list-element "var" specifies this variable

Mean

(list) passed to function points specifying plotting symbols used to indicate mean values per lower-level factor-level, set equal to NULL to omit.

MeanLine

(list) passed to function lines specifying the appearance of horizontal lines indicating mean values of factor levels. The factor variable for which mean-values of factor-levels are plotted can be specified

VCnam

(list) specifying the text-labels (names of variance components) appearing as axis-labels. These parameters are passed to function 'mtext'. Set to NULL to omit VC-names.

useVarNam

(logical) TRUE = each factor-level specifier is pasted to the variable name of the current variable and used as list-element name, FALSE = factor-level specifiers are used as names of list-elements; the former is useful when factor levels are indicated

ylim

(numeric) vector of length two, specifying the limits in Y-direction, if not set these values will be determined automatically.

max.level

(integer) specifying the max. number of levels of a nested factor in order to draw vertical lines. If there are too many levels a black area will be generated by many vertical lines. Level names will also be omitted.

...

further graphical parameters passed on to function 'par', e.g. use 'mar' for specification of margin widths. Note, that not all of them will have an effect, because some are fixed ensuring that a variability chart is drawn.

Value

(invisibly) returns 'Data' with additional variable 'Xcoord' giving X-coordinates of each observation

Details

This function implements a variability-chart, known from, e.g. JMP (JMP, SAS Institute Inc., Cary, NC). Arbitrary models can be specified via parameter 'form'. Formulas will be reduced to a simple hierarchical structure ordering factor-variables according to the order of appearance in 'form'. This is done to make function varPlot applicable to any random model considered in this package. Even if there are main factors, neither one being above or below another main factor, these are forced into a hierachy. Besides the classic scatterplot, where observations are plotted in sub-classes emerging from the model formula, a plot of standard deviations (SD) or coefficients of variation (CV) is provided (type=2) or both types of plots together (type=3).

Examples

Run this code

# load data (CLSI EP05-A2 Within-Lab Precision Experiment)
data(dataEP05A2_3)

dataEP05A2_3$user <- sample(rep(c(1,2), 40))
dataEP05A2_3$cls2 <- sample(rep(c(1,2), 40))

# plot data as variability-chart, using automatically determined parameter
# settings (see 'dynParmSet')
varPlot(y~day/run, dataEP05A2_3)

# display intercept (total mean)
varPlot(y~day/run, dataEP05A2_3, MeanLine=list(var="int"))

# use custom VC-names
varPlot(y~day/run, dataEP05A2_3, VCnam=list(text=c("_Day", "_Run")))

# re-plot now also indicating dayly means as blue horizontal lines
varPlot(y~day/run, dataEP05A2_3, MeanLine=list(var=c("day", "int"), col="blue"))

# now use variable-names in names of individual factor-levels and use a different
# notation of the nesting structure
varPlot(y~day+day:run, dataEP05A2_3, useVarNam=TRUE)

# use alternating backgrounds for each level of factor "day"
# (top-level factor is default)
# use a simplified model formula (NOTE: only valid for function 'varPlot')
varPlot(y~day+run, dataEP05A2_3, BG=list(col=c("lightblue", "lightgray"), border=NA))

# now also color the corresponding row in the table accordingly
varPlot( y~day+run, dataEP05A2_3,
			BG=list(col=c("lightblue", "lightgray"), border=NA, col.table=TRUE))

# assign different point-colors according to a classification variable
# not part of the model (artificial example in this case)
varPlot( y~day+day:run, dataEP05A2_3,
         Points=list(col=list(var="user", col=c("red", "green"))) )

# assign different plotting symbols according to a classification
# variable not part of the model
varPlot( y~day+day:run, dataEP05A2_3,
         Points=list(pch=list(var="user", pch=c(2, 8))) )

# now combine point-coloring and plotting symbols
# to indicate two additional classification variables
varPlot( y~day+day:run, dataEP05A2_3,
         Points=list(col=list(var="user", col=c("red", "green")),
					   	pch=list(var="cls2", pch=c(2, 8))) )

# use magenta lines between each level of factor "run"
varPlot(y~day/run, dataEP05A2_3, BG=list(var="run", border="magenta"))

# plot SDs for each run
varPlot(y~day+day:run, dataEP05A2_3, type=2)

# use CV instead of SD
varPlot(y~day/run, dataEP05A2_3, type=2, VARtype="CV")

# now plot variability-chart and SD-plot in one window
varPlot(y~day/run, dataEP05A2_3, type=3, useVarNam=TRUE)

# now further customize the plot
varPlot( y~day/run, dataEP05A2_3, BG=list(col=c("lightgray", "wheat")),
         YLabel=list(font=2, col="green", cex=1, text="Custom Y-Axis Label"),
         VCnam=list(col="red", font=4),
         VarLab=list(col="magenta", font=3, srt=0))

# create variability-chart of the example dataset in the CLSI EP05-A2
# guidline (listed on p.25)
data(Glucose)
varPlot(result~day/run, Glucose, type=3)

# use individual settings of 'VarLab' and 'VSpace' for each variance component
varPlot(result~day/run, Glucose, type=3,
		   VarLab=list(list(srt=45, col="red", font=2),
		   list(srt=90, col="blue", font=3)), VSpace=c(.25, .75))

# set individual titles for both plot when 'type=3'
varPlot(	result~day/run, Glucose, type=3,
  		Title=list(list(main="Variability Chart"),
  		list(main="Plot of SD-Values")))

# more complex experimental design
data(realData)
Data <- realData[realData$PID == 1,]
varPlot(y~lot/calibration/day/run, Data, type=3)

# improve visual appearance of the plot
varPlot(y~lot/calibration/day/run, Data, type=3, keep.order=FALSE,
  	   BG=list(var="calibration", col=c("white", "lightgray")))

# add horizontal lines indicating mean-value for each factor-level of all variables
varPlot(y~lot/calibration/day/run, Data, type=3, keep.order=FALSE,
  	   BG=list(var="calibration",
				   col=c("aquamarine","antiquewhite2","antiquewhite4",
						 "antiquewhite1","aliceblue","antiquewhite3",
						 "white","antiquewhite","wheat" ),
				   col.table=TRUE),
		   MeanLine=list(var=c("lot", "calibration", "day", "int"),
						 col=c("orange", "blue", "darkgreen", "yellow"),
						 lwd=c(2,2,2,2)))

# now also highlight bounds between factor levels of "lot" and "day"
# as vertical lines and extend them into the table
varPlot(y~lot/calibration/day/run, Data, type=3, keep.order=FALSE,
  	   BG=list(var="calibration",
				   col=c("aquamarine","antiquewhite2","antiquewhite4",
						 "antiquewhite1","aliceblue","antiquewhite3",
						 "white","antiquewhite","wheat" ),
				   col.table=TRUE),
		   MeanLine=list(var=c("lot", "calibration", "day", "int"),
						 col=c("orange", "blue", "darkgreen", "yellow"),
						 lwd=c(2,2,2,2)),
		   VLine=list(var=c("lot", "day"), col=c("black", "skyblue1"),
				      lwd=c(2, 1), col.table=TRUE))

# one can use argument 'JoinLevels' to join factor-levels or a variable
# nested within a higher-level factor, 'VLine' is used to separate levels
# of variables "calibration" and "lot" with different colors
 varPlot(y~calibration/lot/day/run, Data,
 		BG=list(var="calibration",
 				col=c("#f7fcfd","#e5f5f9","#ccece6","#99d8c9",
 				"#66c2a4","#41ae76","#238b45","#006d2c","#00441b"),
 				col.table=TRUE),
			VLine=list(var=c("calibration", "lot"),
 				   col=c("black", "darkgray"), lwd=c(2,1), col.table=TRUE),
 		JoinLevels=list(var="lot", col=c("#ffffb2","orangered","#feb24c"),
 				        lwd=c(2,2,2)),
 		MeanLine=list(var="lot", col="blue", lwd=2))

Run the code above in your browser using DataLab