varianceGraph.cgOneFactorFit {cg}

Equal Variance Graphs assessment of cgOneFactorFit object

Description

Graph residuals of a cgOneFactorFit object to assess equal variance assumption

Usage

## S4 method for signature 'cgOneFactorFit'
varianceGraph(fit, trend = NULL, cgtheme = TRUE,
 device = "single", ...)  

Arguments

fit

A fit object of class cgOneFactorFit.

trend

Add a trend line. When set to the default NULL, the addition of a trend line depends on the following: When there is no censored data, a trend will be added with the lowess smoother. If any censored data residuals are present, then at least 7 groups are needed in the fit for a trend line to be added with the VGAM::vgam smoothing spline. Otherwise, group means are estimated and connected. The values of FALSE and TRUE override this. See Details section below.

cgtheme

When set to the default TRUE, ensures a trellis device is active with limited color scheme. Namely background, strip.shingle, and strip.background are each set to "white".

device

Can be one of three values:

"single"

The default, which will put all graphs on the same device page. For example, when resistant & robust and classical least squares are present and model="both" (the default), a 2 x 1 paneled graph will be created.

"multiple"

Relevant only when resistant & robust and classical least squares are present and model="both" (the default) or model="extended". In those cases, a new graphics device is generated to hold the resistant & robust version, as a single-paneled graph, and the classical least squares version is on the previous device. If model="extended", then a second new graphics device is generated to hold the unweighted resistant & robust residuals, as another single-paneled graph.

"ask"

Relevant only when resistant & robust and classical least squares are present and model="both" (the default) or model="extended". In that case, each are portrayed as a single-paneled graph, with the ask=TRUE argument specified in par so that the user input confirmation is needed before the graphs are drawn.

...

Additional arguments. Two are currently valid:

model

For cgOneFactorFit fit objects that have classical least squares lm() or resistant & robust rlm() fits, the following argument values are possible:

"both"

Graphs of the residuals from both the ordinary classical least squares and resistant & robust fits are plotted. This is the default when both fits are present in the cgOneFactorFit object specified in the fit argument. If the resistant & robust fit is not available, this value is not relevant.

"olsonly"

Only a graph of the residuals from the ordinary classical least squares olsfit fit is performed.

"rronly" or "rrwtdonly"

Only a graph of the weighted residuals from the resistant and robust rrfit fit is plotted.

"rrunwtdonly"

Only a graph of the unweighted residuals from the resistant and robust rrfit fit is plotted.

For other possible cgOneFactorFit fit slots such as accelerated failure time or unequal variance models, the model argument is not relevant, and the appropriate graph will be plotted for these model types.

Details

The graph plots the square root of the absolute value of the residuals against the fitted value. The square root spacing on the y-axis has tick marks in the fitted scale. The notion of using the squared root of the absolute residuals is attributed to John Tukey.

The values are automatically jittered to minimize overlapping points. For censored data, left-censored values are shown as a shallow "V", which is actually just a rotated downward "<" sign. Similarly, right-censored values are shown as a deeper "^", which is a rotated upward ">" sign.

For the trend argument, an added trend line when censored data residuals are present needs to be interpreted cautiously. When there are 7 or more groups, a cubic smoothing spline based on VGAM::vgam is fit; otherwise, the group means of the residuals are estimated with an accelerated failure time model and then just connected. If "too many" censored data values are present, the line may be withheld and warnings will be issued, or if forced with line=TRUE, for example, may appear nonsensical.

The heading for the graph is taken from the cgOneFactorData object, which prepareCGOneFactorData sets from its analysisname argument.

The label for the Y-axis is taken from the cgOneFactorData object, which prepareCGOneFactorData sets from its endptname argument.

The number of decimal places printed in the ticks on the Y-axis is taken from the cgOneFactorData object, which prepareCGOneFactorData sets from its digits argument.

The minimum and maximum values from the range of the absolute valued residuals are respectively labeled in the bottom and top left corners of the graph region.

If group labels along the x-axis seem to overlap in the standard horizontal form, they will be rotated 45 degrees.

Value

varianceGraph.cgOneFactorFit returns an invisible NULL. The main purpose is the side effect of graphing to the current device.

Note

Contact [e-mail] for bug reports, questions, concerns, and comments.

Author(s)

Bill Pikounis [aut, cre, cph], John Oleynick [aut], Eva Ye [ctb]

Examples

## From running examples of cgOneFactorData objects
data(canine)
canine.data <- prepareCGOneFactorData(canine, format="groupcolumns",
                                      analysisname="Canine",
                                      endptname="Prostate Volume",
                                      endptunits=expression(plain(cm)^3),
                                      digits=1, logscale=TRUE, refgrp="CC")
canine.fit <- fit(canine.data)

varianceGraph(canine.fit)

varianceGraph(canine.fit, model="olsonly")


gmcsfcens.data <- prepareCGOneFactorData(gmcsfcens, format="groupcolumns",
                                         analysisname="cytokine",
                                         endptname="GM-CSF (pg/ml)",
                                         logscale=TRUE,
                                         digits=1)

gmcsfcens.fit <- fit(gmcsfcens.data, type="aft")

varianceGraph(gmcsfcens.fit, trend=TRUE)

varianceGraph(gmcsfcens.fit) ## will yield a warning message why no line
                             ## is graphed

varianceGraph(gmcsfcens.fit, trend=FALSE)