consolidateTests {csaw} | R Documentation

## Consolidate window statistics

### Description

Consolidate DB statistics from analyses using multiple window sizes.

### Usage

    consolidateTests(id.list, result.list, weight.list,
        FUN=combineTests, reindex="best", ...)

    consolidateOverlaps(olap.list, result.list, weight.list,
        FUN=combineOverlaps, reindex="best", ...)

### Arguments

`id.list` | A list of integer vectors specifying the identity of the cluster to which each window in each analysis belongs. Typically produced by `consolidateWindows` with `region=NULL`.
`olap.list` | A list of Hits objects specifying the overlaps between windows of each analysis and a common set of pre-defined regions. Typically produced by `consolidateWindows` with `region!=NULL`.
`result.list` | A list of data.frames containing the DB test results for each analysis.
`weight.list` | A list of numeric vectors specifying the weight of each window in `id.list` or overlapping window in `olap.list`.
`FUN` | A function specifying how the statistics should be consolidated, returning a DataFrame with one row per cluster/region.
`reindex` | A character vector indicating which fields of the DataFrame returned by `FUN` should be reindexed.
`...` | Further arguments to pass to `FUN`.

### Details

By default, these functions will use `combineTests` or `combineOverlaps` to consolidate statistics. This will yield a single combined p-value for each cluster or region. Users can obtain the best windows in each cluster/region by setting `FUN=getBestTest` or `FUN=getBestOverlaps` instead.

If `weight.list` is not specified, it is set to `NULL` and a warning is raised. Users should generally pass the weights produced by `consolidateWindows` with `equiweight=TRUE`, to ensure that all window sizes contribute equally to the final result.

### Value

A DataFrame of results computed by `FUN`, see `combineTests` and `getBestTest` for examples. Each row corresponds to a cluster for `consolidateTests` or to a pre-defined region for `consolidateOverlaps`.

### Reindexing

Reindexing is necessary for any fields returned by `FUN` that contain an index for the result table. For example, `"best"` from `getBestTest` refers to the row index with the lowest p-value. This is not sensible when there are multiple result tables, as in `result.list`.

If `reindex` is specified, the consolidation functions will convert the indices into a DataFrame with `"origin"` and `"row"` fields. The former specifies the table in `result.list` and the latter specifies the row of that table that contains the selected window. This DataFrame is stored as a nested DataFrame within the output DataFrame that was originally returned by `FUN`.

### Author(s)

Aaron Lun

### See Also

`consolidateWindows`, `combineTests`, `combineOverlaps`

### Examples

    bamFiles <- system.file("exdata", c("rep1.bam", "rep2.bam"), package="csaw")
    low <- windowCounts(bamFiles, width=1, filter=1)
    med <- windowCounts(bamFiles, width=100, filter=1)
    high <- windowCounts(bamFiles, width=500, filter=1)

    # Mocking up some pretend DB results.
    dbl <- data.frame(logFC=rnorm(nrow(low)), PValue=runif(nrow(low)), logCPM=0)
    dbm <- data.frame(logFC=rnorm(nrow(med)), PValue=runif(nrow(med)), logCPM=0)
    dbh <- data.frame(logFC=rnorm(nrow(high)), PValue=runif(nrow(high)), logCPM=0)

    # Consolidating.
    cons <- consolidateWindows(list(low, med, high),
    	merge.args=list(tol=100, max.width=300))
    comb <- consolidateTests(cons$id, result.list=list(dbl, dbm, dbh),
        weight.list=cons$weight)
    head(comb)

    # Trying with a custom region.
    of.interest <- GRanges(c('chrA', 'chrA', 'chrB', 'chrC'),
        IRanges(c(1, 500, 100, 1000), c(200, 1000, 700, 1500)))
    cons <- consolidateWindows(list(low, med, high), region=of.interest)
    comb <- consolidateOverlaps(cons$olap, result.list=list(dbl, dbm, dbh),
        weight.list=cons$weight)
    head(comb)

[Package csaw version 1.20.0 Index]