coin (version 1.4-3)

SymmetryTest: General Symmetry Test

Description

Testing the symmetry of set of repeated measurements variables measured on arbitrary scales in a complete block design.

Usage

# S3 method for formula
symmetry_test(formula, data, subset = NULL, weights = NULL, ...)
# S3 method for table
symmetry_test(object, ...)
# S3 method for SymmetryProblem
symmetry_test(object, teststat = c("maximum", "quadratic", "scalar"),
              distribution = c("asymptotic", "approximate",
                               "exact", "none"),
              alternative = c("two.sided", "less", "greater"),
              xtrafo = trafo, ytrafo = trafo, scores = NULL,
              check = NULL, paired = FALSE, ...)

Value

An object inheriting from class "IndependenceTest".

Arguments

formula

a formula of the form y1 + ... + yq ~ x | block where y1, ..., yq are measured on arbitrary scales (nominal, ordinal or continuous with or without censoring), x is a factor and block is an optional factor (which is generated automatically if omitted).

data

an optional data frame containing the variables in the model formula.

subset

an optional vector specifying a subset of observations to be used. Defaults to NULL.

weights

an optional formula of the form ~ w defining integer valued case weights for each observation. Defaults to NULL, implying equal weight for all observations. (Not yet implemented!)

object

an object inheriting from classes "table" (with identical dimnames components) or "SymmetryProblem".

teststat

a character, the type of test statistic to be applied: either a maximum statistic ("maximum", default), a quadratic form ("quadratic") or a standardized scalar test statistic ("scalar").

distribution

a character, the conditional null distribution of the test statistic can be approximated by its asymptotic distribution ("asymptotic", default) or via Monte Carlo resampling ("approximate"). Alternatively, the functions asymptotic or approximate can be used. For univariate two-sample problems, "exact" or use of the function exact computes the exact distribution. Computation of the null distribution can be suppressed by specifying "none". It is also possible to specify a function with one argument (an object inheriting from "IndependenceTestStatistic") that returns an object of class "NullDistribution".

alternative

a character, the alternative hypothesis: either "two.sided" (default), "greater" or "less".

xtrafo

a function of transformations to be applied to the factor x supplied in formula; see ‘Details’. Defaults to trafo().

ytrafo

a function of transformations to be applied to the variables y1, ..., yq supplied in formula; see ‘Details’. Defaults to trafo().

scores

a named list of scores to be attached to ordered factors; see ‘Details’. Defaults to NULL, implying equally spaced scores.

check

a function to be applied to objects of class "IndependenceTest" in order to check for specific properties of the data. Defaults to NULL.

paired

a logical, indicating that paired data have been transformed in such a way that the (unstandardized) linear statistic is the sum of the absolute values of the positive differences between the paired observations. Defaults to FALSE.

...

further arguments to be passed to or from other methods (currently ignored).

Details

symmetry_test() provides a general symmetry test for a set of variables measured on arbitrary scales. This function is based on the general framework for conditional inference procedures proposed by Strasser and Weber (1999). The salient parts of the Strasser-Weber framework are elucidated by Hothorn et al. (2006) and a thorough description of the software implementation is given by Hothorn et al. (2008).

The null hypothesis of symmetry is tested. The response variables and the measurement conditions are given by y1, ..., yq and x, respectively, and block is a factor where each level corresponds to exactly one subject with repeated measurements.

A vector of case weights, e.g., observation counts, can be supplied through the weights argument and the type of test statistic is specified by the teststat argument. Influence and regression functions, i.e., transformations of y1, ..., yq and x, are specified by the ytrafo and xtrafo arguments, respectively; see trafo() for the collection of transformation functions currently available. This allows for implementation of both novel and familiar test statistics, e.g., the McNemar test, the Cochran \(Q\) test, the Wilcoxon signed-rank test and the Friedman test. Furthermore, multivariate extensions such as the multivariate Friedman test (Gerig, 1969; Puri and Sen, 1971) can be implemented without much effort (see ‘Examples’).

If, say, y1 and/or x are ordered factors, the default scores, 1:nlevels(y1) and 1:nlevels(x), respectively, can be altered using the scores argument; this argument can also be used to coerce nominal factors to class "ordered". For example, when y1 is an ordered factor with four levels and x is a nominal factor with three levels, scores = list(y1 = c(1, 3:5), x = c(1:2, 4)) supplies the scores to be used. For ordered alternatives the scores must be monotonic, but non-monotonic scores are also allowed for testing against, e.g., umbrella alternatives. The length of the score vector must be equal to the number of factor levels.

The conditional null distribution of the test statistic is used to obtain \(p\)-values and an asymptotic approximation of the exact distribution is used by default (distribution = "asymptotic"). Alternatively, the distribution can be approximated via Monte Carlo resampling or computed exactly for univariate two-sample problems by setting distribution to "approximate" or "exact", respectively. See asymptotic(), approximate() and exact() for details.

References

Gerig, T. (1969). A multivariate extension of Friedman's \(\chi^2_r\)-test. Journal of the American Statistical Association 64(328), 1595--1608. tools:::Rd_expr_doi("10.1080/01621459.1969.10501079")

Hothorn, T., Hornik, K., van de Wiel, M. A. and Zeileis, A. (2006). A Lego system for conditional inference. The American Statistician 60(3), 257--263. tools:::Rd_expr_doi("10.1198/000313006X118430")

Hothorn, T., Hornik, K., van de Wiel, M. A. and Zeileis, A. (2008). Implementing a class of permutation tests: The coin package. Journal of Statistical Software 28(8), 1--23. tools:::Rd_expr_doi("10.18637/jss.v028.i08")

Puri, M. L. and Sen, P. K. (1971). Nonparametric Methods in Multivariate Analysis. New York: John Wiley & Sons.

Strasser, H. and Weber, C. (1999). On the asymptotic theory of permutation statistics. Mathematical Methods of Statistics 8(2), 220--250.

Examples

## One-sided exact Fisher-Pitman test for paired observations
y1 <- c(1.83,  0.50,  1.62,  2.48, 1.68, 1.88, 1.55, 3.06, 1.30)
y2 <- c(0.878, 0.647, 0.598, 2.05, 1.06, 1.29, 1.06, 3.14, 1.29)
dta <- data.frame(
    y = c(y1, y2),
    x = gl(2, length(y1)),
    block = factor(rep(seq_along(y1), 2))
)

symmetry_test(y ~ x | block, data = dta,
              distribution = "exact", alternative = "greater")

## Alternatively: transform data and set 'paired = TRUE'
delta <- y1 - y2
y <- as.vector(rbind(abs(delta) * (delta >= 0), abs(delta) * (delta < 0)))
x <- factor(rep(0:1, length(delta)), labels = c("pos", "neg"))
block <- gl(length(delta), 2)

symmetry_test(y ~ x | block,
              distribution = "exact", alternative = "greater",
              paired = TRUE)


### Example data
### Gerig (1969, p. 1597)
gerig <- data.frame(
    y1 = c( 0.547, 1.811, 2.561,
            1.706, 2.509, 1.414,
           -0.288, 2.524, 3.310,
            1.417, 0.703, 0.961,
            0.878, 0.094, 1.682,
           -0.680, 2.077, 3.181,
            0.056, 0.542, 2.983,
            0.711, 0.269, 1.662,
           -1.335, 1.545, 2.920,
            1.635, 0.200, 2.065),
    y2 = c(-0.575, 1.840, 2.399,
            1.252, 1.574, 3.059,
           -0.310, 1.553, 0.560,
            0.932, 1.390, 3.083,
            0.819, 0.045, 3.348,
            0.497, 1.747, 1.355,
           -0.285, 0.760, 2.332,
            0.089, 1.076, 0.960,
           -0.349, 1.471, 4.121,
            0.845, 1.480, 3.391),
    x = factor(rep(1:3, 10)),
    b = factor(rep(1:10, each = 3))
)

### Asymptotic multivariate Friedman test
### Gerig (1969, p. 1599)
symmetry_test(y1 + y2 ~ x | b, data = gerig, teststat = "quadratic",
              ytrafo = function(data)
                  trafo(data, numeric_trafo = rank_trafo,
                        block = gerig$b)) # L_n = 17.238

### Asymptotic multivariate Page test
(st <- symmetry_test(y1 + y2 ~ x | b, data = gerig,
                     ytrafo = function(data)
                         trafo(data, numeric_trafo = rank_trafo,
                               block = gerig$b),
                     scores = list(x = 1:3)))
pvalue(st, method = "step-down")