cg (version 1.0-3)

comparisonsgraph: Create an graph of comparisons

Description

Creates a graph to see comparisons based on group estimates and variance-covariance matrix

Usage

comparisonsgraph(compstable, difftype, analysisname = "", endptname = "", alpha = 0.05, digits = NULL, titlestamp = TRUE, explanation = TRUE, wraplength = 20, cex.comps = 0.7, ticklabels = NULL, ...)

Arguments

compstable

A comparisonsTable object created by a comparisonsTable method from the cg package. There is one class of objects that is currently available: cgOneFactorComparisonsTable, which is prepared by the comparisonsTable.cgOneFactorFit method.

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 user input confirmation is needed before the graphs are drawn.

wraplength

On the left hand vertical axis are each A vs. B comparison label from the compstable object. An attempt at sensible formatting when a newline is needed is made, but adjustment by this argument may be needed. The default is 20 characters before wrapping to a newline.

cex.comps

Similar to wraplength, adjustment of this argument parameter can be made to fit the comparison labels on the left hand vertical axis.

...

Additional arguments, depending on the specific method written for the compstable object. Currently, there is only one such specific method; see comparisonsGraph.cgOneFactorComparisonsTable for any additional arguments that can be specified.

compstable

A data frame object of form like that created by the comparisons function.

difftype

Must be specified as one of the following:

"percent"

Presumes the estimated differences in compstable are Percent, and thus will space the x-axis logarithmically;

"amount"

Presumes the estimated differences in compstable are Simple Amounts, and thus will space the x-axis in untransformed scale;

"simple"

Synonym for amount, presumes the estimated differences in compstable are Simple Amounts, and thus will space the x-axis in untransformed scale.

analysisname

Optional, a character text or math-valid expression that will used in the graph title. The default value is the empty "".

endptname

Optional, a character text or math-valid expression that that will be used as the x-axis label of the graph. The default value is the empty "".

alpha

Significance level, by default set to 0.05. This is only used for labelling purposes.

digits

Optional, For output display purposes in the graph, 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 data 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.

explanation

If TRUE, which is the default, add explanatory message to the graph rendering about "Error bars that do not cross the zero line indicate statistically significant difference(s)" along with the confidence level derived from alpha.

titlestamp

Specify text to the graph in the top of graph area, otherwise a default description of "Comparisons Graph" and analysisname will be constructed.

wraplength

On the left hand axis are each A vs. B comparison label from the compstable data frame. An attempt at sensible formatting when a newline is needed is made, but adjustment by this argument may be needed. The default is 20 characters before wrapping to a newline.

cex.comps

Similar to wraplength, adjustment of this argument parameter can be made to fit the comparison labels on the left hand axis.

ticklabels

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

...

Additional arguments. None are currently used.

Value

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

Warning

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

Details

The minimum and maximum values across all the bar ends are added inside the plot region in blue, flush against the x-axis. In two panel cases, there is a tendency to fall outside the panel area even though right justified is used for the adj parameter of functions like panel.text.

See Also

comparisons

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)
canine.comps <- comparisonsTable(canine.fit)

## Easier way: notice the camel-case of the comparisonsGraph call

comparisonsGraph(canine.comps, model="olsonly")

## Manual way
## Instead of comparisonsGraph(canine.comps, model="olsonly")

canine.compstable <- comparisons(estimates=canine.fit@olsfit$coef,
                                 varcovmatrix=vcov(canine.fit@olsfit),
                                 errordf=canine.fit@olsfit$df.residual,
                                 endptscale="log",
                                 analysisname="Canine",
                                 digits=1,
                                 endptname="Prostate Volume")

comparisonsgraph(canine.compstable,
                 difftype="percent",
                 analysisname="Canine",
                 digits=1,
                 endptname=expression(paste( plain('Prostate Volume'),
                                      ' (', plain(cm)^3  ,  ')' ))  
                )