wmwTest {BioQC} | R Documentation

## Wilcoxon-Mann-Whitney rank sum test for high-throughput expression profiling data

### Description

wmwTest is a highly efficient Wilcoxon-Mann-Whitney rank sum test for high-dimensional data, such as gene expression profiling. For datasets with more than 100 features (genes), the function can be more than 1,000 times faster than its R implementations (`wilcox.test` in `stats`, or `rankSumTestWithCorrelation` in `limma`).

### Usage

    wmwTest(
      x,
      indexList,
      col = "GeneSymbol",
      valType = c("p.greater", "p.less", "p.two.sided", "U", "abs.log10p.greater",
        "log10p.less", "abs.log10p.two.sided", "Q", "r", "f", "U1", "U2"),
      simplify = TRUE
    )

    ## S4 method for signature 'matrix,IndexList'
    wmwTest(x, indexList, valType = "p.greater", simplify = TRUE)

    ## S4 method for signature 'numeric,IndexList'
    wmwTest(x, indexList, valType = "p.greater", simplify = TRUE)

    ## S4 method for signature 'matrix,GmtList'
    wmwTest(x, indexList, valType = "p.greater", simplify = TRUE)

    ## S4 method for signature 'eSet,GmtList'
    wmwTest(
      x,
      indexList,
      col = "GeneSymbol",
      valType = "p.greater",
      simplify = TRUE
    )

    ## S4 method for signature 'eSet,numeric'
    wmwTest(
      x,
      indexList,
      col = "GeneSymbol",
      valType = "p.greater",
      simplify = TRUE
    )

    ## S4 method for signature 'eSet,logical'
    wmwTest(
      x,
      indexList,
      col = "GeneSymbol",
      valType = "p.greater",
      simplify = TRUE
    )

    ## S4 method for signature 'eSet,list'
    wmwTest(
      x,
      indexList,
      col = "GeneSymbol",
      valType = "p.greater",
      simplify = TRUE
    )

    ## S4 method for signature 'ANY,numeric'
    wmwTest(x, indexList, valType = "p.greater", simplify = TRUE)

    ## S4 method for signature 'ANY,logical'
    wmwTest(x, indexList, valType = "p.greater", simplify = TRUE)

    ## S4 method for signature 'ANY,list'
    wmwTest(x, indexList, valType = "p.greater", simplify = TRUE)

    ## S4 method for signature 'matrix,SignedIndexList'
    wmwTest(x, indexList, valType, simplify = TRUE)

    ## S4 method for signature 'matrix,SignedGenesets'
    wmwTest(x, indexList, valType, simplify = TRUE)

    ## S4 method for signature 'numeric,SignedIndexList'
    wmwTest(x, indexList, valType, simplify = TRUE)

    ## S4 method for signature 'eSet,SignedIndexList'
    wmwTest(x, indexList, valType, simplify = TRUE)

    ## S4 method for signature 'eSet,SignedGenesets'
    wmwTest(
      x,
      indexList,
      col = "GeneSymbol",
      valType = c("p.greater", "p.less", "p.two.sided", "U", "abs.log10p.greater",
        "log10p.less", "abs.log10p.two.sided", "Q", "r", "f", "U1", "U2"),
      simplify = TRUE
    )

### Arguments

`x` | A numeric matrix. All other data types (e.g. numeric vectors or `ExpressionSet` objects) are coerced into matrix.
`indexList` | A list of integer indices (starting from 1) indicating signature genes. Can be of length zero. Other data types (e.g. a list of numeric or logical vectors, or a numeric or logical vector) are coerced into such a list. See `details` below for a special case using GMT files.
`col` | a string sometimes used with a `eSet`
`valType` | The value type to be returned, allowed values include `p.greater`, `p.less`, `abs.log10p.greater` and `abs.log10p.less` (one-sided tests),`p.two.sided`, and `U` statistic (or more specifically, either `U1` or `U2`), and a few other variants. See details below.
`simplify` | Logical. If not, the returning value is in matrix format; if set to `TRUE`, the results are simplified into vectors when possible (default).

### Details

The basic application of the function is to test the enrichment of gene sets in expression profiling data or differentially expressed data (the matrix with feature/gene in rows and samples in columns).

A special case is when `x` is an `eSet` object (e.g. `ExpressionSet`), and `indexList` is a list returned from `readGmt` function. In this case, the only requirement is that one column named `GeneSymbol` in the `featureData` contain gene symbols used in the GMT file. The same applies to signed Gmt files. See the example below.

Besides the conventional value types such as ‘p.greater’, ‘p.less’, ‘p.two.sided’ , and ‘U’ (the U-statistic), `wmwTest` (from version 0.99-1) provides further value types: `abs.log10p.greater` and `log10p.less` perform log10 transformation on respective p-values and give the transformed value a proper sign (positive for greater than, and negative for less than); `abs.log10p.two.sided` transforms two-sided p-values to non-negative values; and `Q` score reports absolute log10-transformation of p-value of the two-side variant, and gives a proper sign to it, depending on whether it is rather greater than (positive) or less than (negative).

From version 1.19.1, the rank-biserial correlation coefficient (‘r’) and the common language effect size (‘f’) are supported value types.

Before version 1.19.3, the ‘U’ statistic returned is in fact ‘U2’. From version 1.19.3, ‘U1’ is returned when ‘U’ is used, and users can specify additional parameter values ‘U1’ and ‘U2’. The sum of ‘U1’ and ‘U2’ is the product of the sizes of two vectors to be compared.

### Value

A numeric matrix or vector containing the statistic.

### Methods (by class)

- `x = matrix,indexList = IndexList`: `x` is a `matrix` and `indexList` is a `IndexList`

- `x = numeric,indexList = IndexList`: `x` is a `numeric` and `indexList` is a `IndexList`

- `x = matrix,indexList = GmtList`: `x` is a `matrix` and `indexList` is a `GmtList`

- `x = eSet,indexList = GmtList`: `x` is a `eSet` and `indexList` is a `GmtList`

- `x = eSet,indexList = numeric`: `x` is a `eSet` and `indexList` is a `numeric`

- `x = eSet,indexList = logical`: `x` is a `eSet` and `indexList` is a `logical`

- `x = eSet,indexList = list`: `x` is a `eSet` and `indexList` is a `list`

- `x = ANY,indexList = numeric`: `x` is `ANY` and `indexList` is a `numeric`

- `x = ANY,indexList = logical`: `x` is `ANY` and `indexList` is a `logical`

- `x = ANY,indexList = list`: `x` is `ANY` and `indexList` is a `list`

- `x = matrix,indexList = SignedIndexList`: `x` is a `matrix` and `indexList` is a `SignedIndexList`

- `x = matrix,indexList = SignedGenesets`: `x` is a `eSet` and `indexList` is a `SignedIndexList`

- `x = numeric,indexList = SignedIndexList`: `x` is a `numeric` and `indexList` is a `SignedIndexList`

- `x = eSet,indexList = SignedIndexList`: `x` is a `eSet` and `indexList` is a `SignedIndexList`

- `x = eSet,indexList = SignedGenesets`: `x` is a `eSet` and `indexList` is a `SignedIndexList`

### Note

The function has been optimized for expression profiling data. It avoids repetitive ranking of data as done by native R implementations and uses efficient C code to increase the performance and control memory use. Simulation studies using expression profiles of 22000 genes in 2000 samples and 200 gene sets suggested that the C implementation can be >1000 times faster than the R implementation. And it is possible to further accelerate by parallel calling the function with `mclapply` in the `multicore` package.

### Author(s)

Jitao David Zhang <jitao_david.zhang@roche.com>, with critical inputs from Jan Aettig and Iakov Davydov about U statistics.

### References

Barry, W.T., Nobel, A.B., and Wright, F.A. (2008). A statistical framework for testing functional namespaces in microarray data. _Annals of Applied Statistics_ 2, 286-315.

Wu, D, and Smyth, GK (2012). Camera: a competitive gene set test accounting for inter-gene correlation. _Nucleic Acids Research_ 40(17):e133

Zar, JH (1999). _Biostatistical Analysis 4th Edition_. Prentice-Hall International, Upper Saddle River, New Jersey.

### See Also

codewilcox.test in the `stats` package, and `rankSumTestWithCorrelation` in the `limma` package.

### Examples

    ## R-native data structures
    set.seed(1887)
    rd <- rnorm(1000)
    rl <- sample(c(TRUE, FALSE), 1000, replace=TRUE)
    wmwTest(rd, rl, valType="p.two.sided")
    wmwTest(rd, which(rl), valType="p.two.sided")
    rd1 <- rd + ifelse(rl, 0.5, 0)
    wmwTest(rd1, rl, valType="p.greater")
    wmwTest(rd1, rl, valType="U")
    rd2 <- rd - ifelse(rl, 0.2, 0)
    wmwTest(rd2, rl, valType="p.greater")
    wmwTest(rd2, rl, valType="p.two.sided")
    wmwTest(rd2, rl, valType="p.less")
    wmwTest(rd2, rl, valType="r")
    wmwTest(rd2, rl, valType="f")

    ## matrix forms
    rmat <- matrix(c(rd, rd1, rd2), ncol=3, byrow=FALSE)
    wmwTest(rmat, rl, valType="p.two.sided")
    wmwTest(rmat, rl, valType="p.greater")

    wmwTest(rmat, which(rl), valType="p.two.sided")
    wmwTest(rmat, which(rl), valType="p.greater")

    ## other valTypes
    wmwTest(rmat, which(rl), valType="U")
    wmwTest(rmat, which(rl), valType="abs.log10p.greater")
    wmwTest(rmat, which(rl), valType="log10p.less")
    wmwTest(rmat, which(rl), valType="abs.log10p.two.sided")
    wmwTest(rmat, which(rl), valType="Q")
    wmwTest(rmat, which(rl), valType="r")
    wmwTest(rmat, which(rl), valType="f")

    ## using ExpressionSet
    data(sample.ExpressionSet)
    testSet <- sample.ExpressionSet
    fData(testSet)$GeneSymbol <- paste("GENE_",1:nrow(testSet), sep="")
    mySig1 <- sample(c(TRUE, FALSE), nrow(testSet), prob=c(0.25, 0.75), replace=TRUE)
    wmwTest(testSet, which(mySig1), valType="p.greater")

    ## using integer
    exprs(testSet)[,1L] <- exprs(testSet)[,1L] + ifelse(mySig1, 50, 0)
    wmwTest(testSet, which(mySig1), valType="p.greater")

    ## using lists
    mySig2 <- sample(c(TRUE, FALSE), nrow(testSet), prob=c(0.6, 0.4), replace=TRUE)
    wmwTest(testSet, list(first=mySig1, second=mySig2))
    ## using GMT file
    gmt_file <- system.file("extdata/exp.tissuemark.affy.roche.symbols.gmt", package="BioQC")
    gmt_list <- readGmt(gmt_file)

    gss <- sample(unlist(sapply(gmt_list, function(x) x$genes)), 1000)
    eset<-new("ExpressionSet",
             exprs=matrix(rnorm(10000), nrow=1000L),
             phenoData=new("AnnotatedDataFrame", data.frame(Sample=LETTERS[1:10])),
             featureData=new("AnnotatedDataFrame",data.frame(GeneSymbol=gss)))
    esetWmwRes <- wmwTest(eset ,gmt_list, valType="p.greater")
    summary(esetWmwRes)

    ## using signed GMT file
    signed_gmt_file <- system.file("extdata/test.gmt", package="BioQC")
    signed_gmt <- readSignedGmt(signed_gmt_file)
    esetSignedWmwRes <- wmwTest(eset, signed_gmt, valType="p.greater")

    esetMat <- exprs(eset); rownames(esetMat) <- fData(eset)$GeneSymbol
    esetSignedWmwRes2 <- wmwTest(esetMat, signed_gmt, valType="p.greater")

[Package BioQC version 1.22.0 Index]