Create a table of comparisons based on group estimates and variance-covariance matrix. Pairwise or custom specified contrasts are estimated and tested.
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")Creates a return data frame object that specifies the comparison of the form A vs. B in each row, and with these columns:
estimateThe difference in group estimates in the
comparison: A vs. B. If endptscale="log",
this will be back-transformed to a percent
difference scale.
seThe 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.
lowerciThe 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.
upperciThe 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.
pvalThe computed p-value from the test of the difference estimate.
meanA or geomeanAThe 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.
seAThe 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 geomeanBThe 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.
seBThe 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.
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.
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.
Can be one of three types of values:
InfThe default, and will just use standard Gaussian (normal) distribution quantile for the critical points in each comparison;
numericA 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.
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.
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.
Significance level, by default set to 0.05 to
correspond to 95% confidence.
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.
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.
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.
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.
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 .
Optional, a character text that will be
printed along with the results table. The default
value is the empty "".
Optional, a character text that will be
printed along with the results table. The default
value is the empty "".
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.
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.
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.
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.
Bill Pikounis [aut, cre, cph], John Oleynick [aut], Eva Ye [ctb]
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.
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.
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")
Run the code above in your browser using DataLab