comparisonsTable.cgOneFactorFit {cg}

Create a table of comparisons amongst groups with the cgOneFactorFit object

Description

Create a table of comparisons based on the cgOneFactorFit object. Pairwise or custom specified contrasts are estimated and tested. A cgOneFactorComparisonsTable class object is created.

Usage

## S4 method for signature 'cgOneFactorFit'
comparisonsTable(fit, type="pairwisereflect",
 alpha=0.05, addpct=FALSE, display="print", ...)

Arguments

fit

An object of class cgOneFactorFit.

type

Can be one of four values:

"pairwisereflect"

The default value, it calculates and lists all possible pairwise comparison permutations, as each pair order is included. In other words, Groups A vs. B and B vs. A will be included.

"pairwise"

Calculates and lists all possible pairwise comparison combinations. Once a pair such as Groups A vs. B is specified, then the reflective B vs. A is not included. So the number of comparisons is half that produced by "pairwisereflect". The ordering of group levels in the fit object is used to determine which ordering is included and which is not. If all orderings are of interest, such as for settings$endptscale=="log" in the fit objects, use the "pairwisereflect" value above.

"allgroupstocontrol"

Takes the value of settings$refgrp in the cg fit object, deems it the "control" group, and constructs pairwise comparisons of all other groups to it. This setting is required when the refgrp argument is specified in the call (see ... section below.)

"custom"

Indicates the a custom matrix of comparisons will be constructed, and that matrix needs to be specified in the contrastmatrix argument.

alpha

Significance level, by default set to 0.05.

addpct

Only relevant if settings$endptscale=="original" in the fit object. An column of percent differences is added for the comparisons, as a descriptive supplement to the original scale differences that are formally estimated.

display

One of three valid values:

"print"

The default value; It calls a print method for the created
cgOneFactorComparisonsTable object, which is a formatted text output of the table(s).

"none"

Supresses any printing. Useful, for example, when just assignment of the resulting object is desired.

"show"

Calls the default showDefault method, which will just print out the cgOneFactorComparisonsTable components.

...

Additional arguments.

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 conduct the adjusted comparisons.

contrastmatrix

Only relevant if type="custom" is specified. In that case, a numeric matrix with the number of rows equal to the number of comparisons of interest. The number of columns must be equal to the number of group means. Each row in the matrix is assumed to represent a contrast of coefficients amongst the groups that defines the comparison of interest.

refgrp

If left at the default value of NULL, it will be set to the settings$refgrp value in the cg fit object. When set, it is deemed the "reference", or "control" group, so that pairwise comparisons of all other groups to it will be constructed when type="allgroupstocontrol". Please note the type="allgroupstocontrol" setting is REQUIRED when the refgrp argument is specified in the call with a valid non-NULL value.

model

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

"both"

Comparison tables based on both the ordinary classical least squares and resistant & robust fits are created. 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 comparison table based on the ordinary classical least squares olsfit fit slot is performed.

"rronly"

Only a comparison table based on the resistant and robust rrfit fit slot is performed.

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

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.

The multcomp package provides a unified way to calculate critical points based on the comparisons of interest in a "family". Thus a user does not need to worry about choosing amongst the myriad names of multiple comparison procedures.

Value

Creates an object of class cgOneFactorComparisonsTable, with the following slots:

ols.comprs

The table of comparisons based on the olsfit component of the cgOneFactorFit, unless model="rronly" is specified. In that case the slot value is NULL. Will not be appropriate in the case where a valid aftfit component is present in the cgOneFactorFit object. See below for the data frame structure of the table.

rr.comprs

The table of comparisons based on the rrfit component of the cgOneFactorFit object, if a valid resistant & robust fit object is present. If rrfit is a simple character value of "No fit was selected.", or model="olsonly" was specified, then the value is NULL. See below for the data frame structure of the table.

aft.comprs

The table of comparisons based on the aftfit component of the cgOneFactorFit object if a valid accelerated failure time fit object is present. If aftfit is a simple character value of "No fit was selected.", then the value is NULL. See below for the data frame structure of the table.

uv.comprs

The table of comparisons based on the uvfit component of the cgOneFactorFit object if a valid unequal variances fit object is present. The error degrees of freedom for each comparison estimate and test is individually estimated with a Satterthwaite approximation. See below for the data frame structure of the table.

settings

A list of settings carried from the cgOneFactorFit fit object, and the addition of some specified arguments in the method call above: alpha, mcadjust, type, and addpct. These are used for the print.cgOneFactorComparisonsTable method, invoked for example when display="print".

The data frame structure of the comparisons table in a *.comprs slot consists of row.names that specify the comparison of the form A vs. B, and these columns:

estimate

The difference in group means in the comparison: A vs. B. If settings$endptscale=="log" in the fit object, this will be back-transformed to a percent difference scale.

se

The estimated standard error of the difference estimate. If settings$endptscale=="log" in the fit object, this estimate will be based on the Delta method, and will particularly begin to be a poor approximation when the standard error in the logscale exceeds 0.50.

lowerci

The lower 100 * (1-alpha) % confidence limit of the difference estimate. With the default alpha=0.05, this is 95%. If settings$endptscale=="log" in the fit object, the confidence limit is first computed in the logarithmic scale of analysis, and then back-transformed to a percent difference scale.

upperci

The upper 100 * (1-alpha) % confidence limit of the difference estimate. With the default alpha=0.05, this is 95%. If settings$endptscale=="log" in the fit object, the confidence limit is first computed in the logarithmic scale of analysis, and then back-transformed to a percent difference scale.

pval

The computed p-value from the test of the difference estimate.

meanA or geomeanA

The estimated mean for the left hand side "A" of the A vs. B comparison. If settings$endptscale=="log" in the fit object, this is a back-transform to the original scale, and therefore is a geometric mean, and will be labelled geomeanA. Otherwise it is the arithmetic mean and labelled meanA.

seA

The estimated standard error of the meanA estimate. If settings$endptscale=="log" in the fit object, this estimate will be based on the Delta method, and will particularly begin to be a poor approximation when the standard error in the logscale exceeds 0.50.

meanB or geomeanB

The estimated mean for the right hand side "B" of the A vs. B comparison. If settings$endptscale=="log" in the fit object, this is a back-transform to the original scale, and therefore is a geometric mean, and will be labelled geomeanB. Otherwise it is the arithmetic mean and labelled meanB.

seB

The estimated standard error of the meanB estimate. If settings$endptscale=="log" in the fit object, this estimate will be based on the Delta method, and will particularly begin to be a poor approximation when the standard error in the logscale exceeds 0.50.

An additional column addpct of percent differences is added if endptscale=="original" and addpct=TRUE, as a descriptive supplement to the original scale differences that are formally estimated.

Note

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

Author(s)

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

References

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

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

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

canine.comps1 <- comparisonsTable(canine.fit,  mcadjust=TRUE,
                                   type="allgroupstocontrol", refgrp="CC")


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

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

gmcsfcens.comps <- comparisonsTable(gmcsfcens.fit)