getBestTest {csaw} | R Documentation

## Get the best test in a cluster

### Description

Find the test with the strongest evidence for rejection of the null in each cluster.

### Usage

    getBestTest(ids, tab, by.pval=TRUE, weights=NULL, pval.col=NULL, cpm.col=NULL)

### Arguments

`ids` | an integer vector or factor containing the cluster ID for each test
`tab` | a table of results with a `PValue` field for each test
`by.pval` | a logical scalar, indicating whether selection should be performed on corrected p-values
`weights` | a numeric vector of weights for each window, defaults to 1 for each test
`pval.col` | an integer scalar or string specifying the column of `tab` containing the p-values
`cpm.col` | an integer scalar or string specifying the column of `tab` containing the log-CPM values

### Details

Clusters are identified as those tests with the same value of `ids` (any `NA` values are ignored). If `by.pval=TRUE`, this function identifies the test with the lowest p-value as that with the strongest evidence against the null in each cluster. The p-value of the chosen test is adjusted using the Bonferroni correction, based on the total number of tests in the parent cluster. This is necessary to obtain strong control of the family-wise error rate such that the best test can be taken from each cluster for further consideration.

The importance of each window in each cluster can be adjusted by supplying different relative `weights` values. Each weight is interpreted as a different threshold for each test in the cluster. Larger weights correspond to lower thresholds, i.e., less evidence is needed to reject the null for tests deemed to be more important. This may be useful for upweighting particular tests, e.g., windows containing a motif for the TF of interest.

Note the difference between this function and `combineTests`. The latter presents evidence for any rejections within a cluster. This function specifies the exact location of the rejection in the cluster, which may be more useful in some cases but at the cost of conservativeness. In both cases, clustering procedures such as `mergeWindows` can be used to identify the cluster.

If `by.pval=FALSE`, the best test is defined as that with the highest log-CPM value. This should be independent of the p-value so no adjustment is necessary. Weights are not applied here. This mode may be useful when abundance is correlated to rejection under the alternative hypothesis, e.g., picking high-abundance regions that are more likely to contain peaks.

By default, the relevant fields in `tab` are identified by matching the column names to their expected values. If the column names are different from what is expected, specification of the correct column can be performed using `pval.col` and `cpm.col`.

### Value

A DataFrame with one row per cluster and the numeric fields `best`, the index for the best test in the cluster; `PValue`, the (possibly adjusted) p-value for that test; and `FDR`, the q-value corresponding to the adjusted p-value. Note that the p-value column may be named differently if `pval.col` is specified. Other fields in `tab` corresponding to the best test in the cluster are also returned. Cluster IDs are stored as the row names.

### Author(s)

Aaron Lun

### References

Wasserman, L, and Roeder, K (2006). Weighted hypothesis testing. arXiv preprint math/0604172.

### See Also

`combineTests`, `mergeWindows`

### Examples

    ids <- round(runif(100, 1, 10))
    tab <- data.frame(logFC=rnorm(100), logCPM=rnorm(100), PValue=rbeta(100, 1, 2))
    best <- getBestTest(ids, tab)
    head(best)

    best <- getBestTest(ids, tab, cpm.col="logCPM", pval.col="PValue")
    head(best)

    # With window weighting.
    w <- round(runif(100, 1, 5))
    best <- getBestTest(ids, tab, weight=w)
    head(best)

    # By logCPM.
    best <- getBestTest(ids, tab, by.pval=FALSE)
    head(best)

    best <- getBestTest(ids, tab, by.pval=FALSE, cpm.col=2, pval.col=3)
    head(best)

[Package csaw version 1.20.0 Index]