cg (version 1.0-3)

errorbargraph: Create an Error Bar graph amongst groups

Description

Generic function to create a Error Bar graph based on a fit by the cg package.

Usage

errorBarGraph(fit, mcadjust=FALSE, alpha = 0.05, cgtheme = TRUE, device="single", ...)

Arguments

estimates

A named vector of estimates. Each estimate element is a measure that will be the center of the error bar of the group. The name of each group must be present in the names attribute of the vector.

centralvar

A single variance value to be used for each group's error bar construction. In the canonical case it is the square of the estimated standard error of the mean estimate of the group, where each group also has the same standard error (and sample size). If the standard errors / variances are similar enough across the groups, the visualization may still be effective even though the error bar lengths will be approximations.

critpoint

The single critical value of the theoretical reference distribution. In the canonical case it is the t-distribution quantile for estimates derived from a standard linear model with homoscedastic variance. It could also reflect a multiplicity adjustment, or like the centralvar discussion in the previous item, it may serve as part of a visually useful approximation for other cases.

endptscale

Must be specified as "log" or "original". If the default "log" then the y-axis will be created with a logarithmic spacing. The tick marks will be calculated accordingly and expressed in the original scale of the estimates. The estimates vector must already be in the logarithmic scale.

analysisname

Optional, a character text or math-valid expression that will be set for default use in graph title and table methods. The default value is the empty "".

endptname

Optional, a character text or math-valid expression that will be set for default use as the y-axis label of graph methods, and also used for table methods. The default value is the empty "".

alpha

Significance level, by default set to 0.05, which equates to a 95% confidence level. This is just used for labelling purposes.

digits

Optional, for output display purposes in graphs and table methods, values will be rounded to this numeric value. Only the integers of 0, 1, 2, 3, and 4 are accepted. No rounding is done during any calculations. The default value is NULL, which will examine each individual estimates value and choose the one that has the maximum number of digits after any trailing zeroes are ignored. The max number of digits will be 4.

approxstamp

Add text to the graph that acknowledges that the error bar method is approximate.

titlestamp

Add text to the top margin above the graph area.

offset

Optional, if for example a numeric constant was added to all response values before calculation of the estimate as a mean, this could be used to shift the axis marks appropriately. The default value is NULL.

ticklabels

Optional, before graphing the data, remove any automatically generated tickmarks for the y-axis, and use these tickmarks instead. A vector of tickmarks to be placed on the y-axis. Any numeric representations will be coerced to character.

...

Additional arguments. None are currently used.

fit

A fit object created by a fit method from the cg package.

mcadjust

Do a multiple comparisons adjustment, based on the simultaneous inference capabilities of the multcomp package. See Details below. The default value is FALSE. If mcadjust=TRUE is specified, there will be a delay, usually just for a few seconds, due to computing time of the critical point in order to create the error bar intervals.

alpha

Significance level, by default set to 0.05 so that confidence levels are 95%.

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 graph panels on the same device page.

"multiple"

Relevant only when more than one panel of graphs is possible. In that case, a new graphics device is generated each newly generated single-paneled graph.

"ask"

Relevant only when more than one panel of graphs is possible. 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, depending on the specific method written for the object. See the method-specific documentation for additional details.

Value

The main purpose is the side effect of graphing to the current device. See specific methods for discussion of any return values.

Warning

This function was created for internal use in the cg package as its use can be seen in the errorBarGraph methods code. Therefore any direct use of it needs to be done cautiously.

Details

When mcadjust=TRUE, a status message of "Some time may be needed" "as the critical point from the multcomp::summary.glht function call is calculated" is displayed at the console. This computed critical point is used for all subsequent p-value and confidence interval calculations.

References

Hothorn, T., Bretz, F., Westfall, P., Heiberger, R.M., and Schuetzenmeister, A. (2010). The multcomp R package.

Hothorn, T., Bretz, F., and Westfall, P. (2008). "Simultaneous Inference in General Parametric Models", Biometrical Journal, 50, 3, 346-363.

See Also

errorBarGraph.cgOneFactorFit

Examples

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)

errorBarGraph(canine.fit)

errorBarGraph(canine.fit, mcadjust=TRUE, model="olsonly")