comparisons {cg}

Create a table of comparisons amongst groups

Description

Create a table of comparisons based on group estimates and variance-covariance matrix. Pairwise or custom specified contrasts are estimated and tested.

Usage

comparisons(estimates, varcovmatrix, errordf = Inf, endptscale,
            mcadjust = FALSE, alpha = 0.05, type = "pairwisereflect",
            contrastmatrix = NULL, n, offset = NULL, cnames = "derive",
            analysisname = "", endptname = "", digits = NULL, addpct = FALSE,
            display = "print") 

Arguments

estimates

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

varcovmatrix

The estimated variance-covariance matrix associated with the estimates. Must have the same number of columns and rows as the length of the estimates vector.

errordf

Can be one of three types of values:

Inf

The default, and will just use standard Gaussian (normal) distribution quantile for the critical points in each comparison;

numeric

A finite positive number that will be used for the degrees of freedom for the t-distribution quantile;

"approx"

Will try to apply a Satterthwaite approximation based on the variance-covariance matrix and n to estimate the degrees of freedom for each comparison. The variance-covariance matrix will need to be diagonal. Only will be accepted when mcadjust=FALSE.

endptscale

Must be specified as "log" or "original". If "log" then the estimates vector is assumed to be in the log scale, and calculations will transform it to the original scale for the generated table.

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.

alpha

Significance level, by default set to 0.05 to correspond to 95% confidence.

type

Can be one of four values:

"pairwisereflect"

The default value, it calculates and lists all possible pairwise comparison permutations, as each pair ordering 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 presented is half that produced by "pairwisereflect". The ordering of group levels in the estimates vector is used to determine which ordering is included and which is not. If all orderings are of interest, such as for endptscale=="log", use the "pairwisereflect" value above.

"allgroupstocontrol"

Takes the first element group of the estimate vector, deems it the "control" group, and constructs pairwise comparisons of all other groups to it.

"custom"

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

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 is needed. The number of columns must be equal to the number of groups in the estimate vector. Each row in the matrix is assumed to represent a contrast of coefficients amongst the groups that defines the comparison of interest.

n

Needs to be specified only when errordf="approx". In this case it needs to be a vector of group sample sizes, the same in length as the estimates vector.

offset

Optional, If for example a numeric constant was added to all response values before calculation of the estimates as means in the "log" scale, this could be used to adjust the estimates and comparisons appropriately. The default is NULL.

cnames

If the default value of "derive" is used, row names are derived for the table that reflect the A vs. B type of comparison items in each row, using the names attrributes of the estimates vector and the middle term of "vs." Otherwise, this can be explicitly specified and needs to be a character vector of the same length as estimates .

analysisname

Optional, a character text that will be printed along with the results table. The default value is the empty "".

endptname

Optional, a character text that will be printed along with the results table. The default value is the empty "".

digits

Optional, For output display purposes, 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.

addpct

Only relevant if endptscale=="original". 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 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 comparisons return object.

Details

Only two-sided Wald-type of confidence intervals are possible with this function.

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 a return data frame object that specifies the comparison of the form A vs. B in each row, and with these columns:

estimate

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

se

The estimated standard error of the difference estimate. If endptscale="log", 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 endptscale="log", 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 endptscale="log", 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 endptscale="log", 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 endptscale="log", 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 endptscale="log", 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 endptscale="log", 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.

Warning

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

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)


## Easier way: notice the comparisonsTable call

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

## Manual way
## Instead of comparisonsTable(canine.fit, model="olsonly")

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")