SimTestDiff: Simultaneous Tests for General Contrasts (Differences) of...
In SimComp: Simultaneous Comparisons for Multiple Endpoints

Description Usage Arguments Details Value Note Author(s) References See Also Examples

Simultaneous tests for general contrasts (linear functions) of normal means (e.g., "Dunnett", "Tukey", "Williams" ect.), and for single or multiple endpoints (primary response variables) simultaneously. The procedure of Hasler and Hothorn (2011) <doi:10.2202/1557-4679.1258> is applied for differences of means of normally distributed data. The variances/ covariance matrices of the treatment groups (containing the covariances between the endpoints) may be assumed to be equal or possibly unequal for the different groups (Hasler, 2014 <doi:10.1515/ijb-2012-0015>). For the case of only a single endpoint and unequal covariance matrices (variances), the procedure coincides with the PI procedure of Hasler and Hothorn (2008) <doi:10.1002/bimj.200710466>.

## Default S3 method:
SimTestDiff(data, grp, resp = NULL, na.action = "na.error", type = "Dunnett", 
  base = 1, ContrastMat = NULL, alternative = "two.sided", Margin = 0, 
  covar.equal = FALSE, CorrMatDat = NULL, ...)
## S3 method for class 'formula'
SimTestDiff(formula, ...)

`data`	a data frame containing a grouping variable and the endpoints as columns
`grp`	a character string with the name of the grouping variable
`resp`	a vector of character strings with the names of the endpoints; if `resp=NULL` (default), all column names of the data frame without the grouping variable are chosen automatically
`formula`	a formula specifying a numerical response and a grouping factor (e.g. `response ~ treatment`)
`na.action`	a character string indicating what should happen when the data contain `NAs`; if `na.action="na.error"` (default) the procedure stops with an error message; if `na.action="multi.df"` multiple marginal degrees of freedom are used to adjust for the missing values problem
`type`	a character string, defining the type of contrast, with the following options: "Dunnett": many-to-one comparisons "Tukey": all-pair comparisons "Sequen": comparisons of consecutive groups "AVE": comparison of each group with average of all others "GrandMean": comparison of each group with grand mean of all groups "Changepoint": differences of averages of groups of higher order to averages of groups of lower order "Marcus": Marcus contrasts "McDermott": McDermott contrasts "Williams": Williams trend tests "UmbrellaWilliams": Umbrella-protected Williams trend tests note that `type` is ignored if `ContrastMat`is specified by the user (see below)
`base`	a single integer specifying the control group for Dunnett contrasts, ignored otherwise
`ContrastMat`	a contrast matrix, where columns correspond to groups and rows correspond to contrasts
`alternative`	a character string specifying the alternative hypothesis, must be one of `"two.sided"` (default), `"greater"` or `"less"`
`Margin`	a single numeric value, or a numeric vector corresponding to endpoints, or a matrix where columns correspond to endpoints and rows correspond to contrasts
`covar.equal`	a logical variable indicating whether to treat the variances/ covariance matrices of the treatment groups (containing the covariances between the endpoints) as being equal; if `TRUE` then the pooled variance/ covariance matrix is used, otherwise the Satterthwaite approximation to the degrees of freedom is used
`CorrMatDat`	a correlation matrix of the endpoints, if `NULL` (default) it is estimated from the data
`...`	arguments to be passed to SimTestDiff.default

The interest is in simultaneous tests for several linear combinations (contrasts) of treatment means in a one-way ANOVA model, and for single or multiple endpoints simultaneously. For example, the all-pair comparison of Tukey (1953) and the many- to-one comparison of Dunnett (1955) are implemented, but allowing for heteroscedasticity and multiple endpoints. The user is also free to create other interesting problem-specific contrasts. Approximate multivariate t- distributions are used to calculate (adjusted) p-values (Hasler and Hothorn, 2011 <doi:10.2202/1557-4679.1258>). This approach controls the familywise error rate in admissible ranges and in the strong sense. The variances/ covariance matrices of the treatment groups (containing the covariances between the endpoints) can be assumed to be equal (covar.equal=TRUE) or unequal (covar.equal=FALSE). If being equal, the pooled variance/ covariance matrix is used, otherwise approximations to the degrees of freedom (Satterthwaite, 1946) are used (Hasler, 2014 <doi:10.1515/ijb-2012-0015>; Hasler and Hothorn, 2008 <doi:10.1002/bimj.200710466>). Unequal covariance matrices occure if variances or correlations of some endpoints differ depending on the treatment groups.

An object of class SimTest containing:

`estimate`	a matrix of estimated differences
`statistic`	a matrix of the calculated test statistics
`p.val.raw`	a matrix of raw p-values
`p.val.adj`	a matrix of p-values adjusted for multiplicity
`CorrMatDat`	if not prespecified by `CorrMatDat`, either the estimated common correlation matrix of the endpoints (`covar.equal=TRUE`) or a list of different (one for each treatment) estimated correlation matrices of the endpoints (`covar.equal=FALSE`)
`CorrMatComp`	the estimated correlation matrix of the comparisons
`degr.fr`	a matrix of degrees of freedom

By default (na.action="na.error"), the procedure stops if there are missing values. A new experimental version for missing values is used if na.action="multi.df". If covar.equal=TRUE, the number of endpoints must not be greater than the total sample size minus the number of treatment groups. If covar.equal=FALSE, the number of endpoints must not be greater than the minimal sample size minus 1. Otherwise the procedure stops.

All hypotheses are tested with the same test direction for all comparisons and endpoints (alternative="..."). In case of doubt, use "two.sided".

If Margin is a single numeric value or a numeric vector, then the same value(s) are used for the remaining comparisons or endpoints.

Mario Hasler

Hasler, M. and Hothorn, L.A. (2018): Multi-arm trials with multiple primary endpoints and missing values. Statistics in Medicine 37, 710–721, <doi:10.1002/sim.7542>.

Hasler, M. (2014): Multiple contrast tests for multiple endpoints in the presence of heteroscedasticity. The International Journal of Biostatistics 10, 17–28, <doi:10.1515/ijb-2012-0015>.

Hasler, M. and Hothorn, L.A. (2011): A Dunnett-type procedure for multiple endpoints. The International Journal of Biostatistics 7, Article 3, <doi:10.2202/1557-4679.1258>.

Hasler, M. and Hothorn, L.A. (2008): Multiple contrast tests in the presence of heteroscedasticity. Biometrical Journal 50, 793–800, <doi:10.1002/bimj.200710466>.

SimCiDiff, SimTestRat, SimCiRat

# Example 1:
# A comparison of the groups B and H against the standard S, for endpoint
# Thromb.count, assuming unequal variances for the groups. This is an
# extension of the well-known Dunnett-test to the case of heteroscedasticity.

data(coagulation)

comp1 <- SimTestDiff(data=coagulation, grp="Group", resp="Thromb.count",
  type="Dunnett", base=3, alternative="greater", covar.equal=FALSE)
comp1

# Example 2:
# A comparison of the groups B and H against the standard S, simultaneously
# for all endpoints, assuming unequal covariance matrices for the groups. This is
# an extension of the well-known Dunnett-test to the case of heteroscedasticity
# and multiple endpoints.

data(coagulation)

comp2 <- SimTestDiff(data=coagulation, grp="Group", resp=c("Thromb.count","ADP","TRAP"),
  type="Dunnett", base=3, alternative="greater", covar.equal=FALSE)
summary(comp2)

 
Test for differences of means of multiple endpoints 
Assumption: Heterogeneous covariance matrices for the groups 
Alternative hypotheses: True differences greater than the margins 
 
      comparison     endpoint margin estimate statistic degr.fr p.value.raw
B - S      B - S Thromb.count      0   0.1217    1.3327   17.95      0.1001
H - S      H - S Thromb.count      0   0.0435    0.4244   17.67      0.3383
      p.value.adj
B - S      0.1778
H - S      0.5224
 
 
Contrast matrix: 

	 Multiple Comparisons of Means: Dunnett Contrasts

      B H  S
B - S 1 0 -1
H - S 0 1 -1
 
Estimated covariance matrices of the data: 
$B
             Thromb.count    ADP    TRAP
Thromb.count       0.0626 0.0565 -0.0102
ADP                0.0565 0.0638  0.0054
TRAP              -0.0102 0.0054  0.0963

$H
             Thromb.count    ADP   TRAP
Thromb.count       0.0943 0.0637 0.0663
ADP                0.0637 0.0518 0.0446
TRAP               0.0663 0.0446 0.1157

$S
             Thromb.count    ADP   TRAP
Thromb.count       0.0318 0.0132 0.0598
ADP                0.0132 0.0079 0.0269
TRAP               0.0598 0.0269 0.1376

 
Estimated correlation matrices of the data: 
$B
             Thromb.count    ADP    TRAP
Thromb.count       1.0000 0.8937 -0.1314
ADP                0.8937 1.0000  0.0687
TRAP              -0.1314 0.0687  1.0000

$H
             Thromb.count    ADP   TRAP
Thromb.count       1.0000 0.9121 0.6348
ADP                0.9121 1.0000 0.5770
TRAP               0.6348 0.5770 1.0000

$S
             Thromb.count    ADP   TRAP
Thromb.count       1.0000 0.8338 0.9033
ADP                0.8338 1.0000 0.8161
TRAP               0.9033 0.8161 1.0000

 
Estimated correlation matrix of the comparisons: 
             Thromb.count    ADP   TRAP Thromb.count    ADP   TRAP
Thromb.count       1.0000 0.8494 0.3122       0.2833 0.1708 0.3755
ADP                0.8494 1.0000 0.2387       0.1335 0.1158 0.1917
TRAP               0.3122 0.2387 1.0000       0.3417 0.2232 0.5550
Thromb.count       0.2833 0.1335 0.3417       1.0000 0.8869 0.7054
ADP                0.1708 0.1158 0.2232       0.8869 1.0000 0.5818
TRAP               0.3755 0.1917 0.5550       0.7054 0.5818 1.0000
 
Alternative hypotheses: True differences greater than the margins 
 
  comparison     endpoint margin estimate statistic degr.fr p.value.raw
1      B - S Thromb.count      0   0.1217    1.3327   12.25      0.1001
2      B - S          ADP      0   0.2121    2.6398   12.25      0.0108
3      B - S         TRAP      0   0.1053    0.7402   12.25      0.2339
4      H - S Thromb.count      0   0.0435    0.4244   14.27      0.3383
5      H - S          ADP      0   0.0842    1.1949   14.27      0.1260
6      H - S         TRAP      0   0.0711    0.4894   14.27      0.3148
  p.value.adj
1      0.3204
2      0.0431
3      0.5877
4      0.7294
5      0.3749
6      0.7018