ResultList wrappers {csaw} | R Documentation

## Wrappers to combine multiple analyses

### Description

Convenience wrappers around lower-level functions to easily obtain region-level results from multiple sets of windows, each with their own statistics.

### Usage

    mergeResultsList(ranges.list, tab.list=NULL, tol, equiweight=TRUE,
        get.best=TRUE, merge.args=list(), combine.args=list(),
        best.args=list())

    overlapResultsList(ranges.list, tab.list=NULL, regions, equiweight=TRUE,
        get.best=TRUE, overlap.args=list(), combine.args=list(),
        best.args=list())

### Arguments

`ranges.list` | A list of GRanges or RangedSummarizedExperiment objects, usually containing windows of varying sizes from separate calls to `windowCounts`.
`tab.list` | A list of data.frames of differential binding results, usually from separate analyses at differing window sizes. Each should contain one row per interval for the corresponding entry of `ranges.list`. If `NULL`, defaults to a list containing the `mcols` of each entry of `ranges.list`.
`tol` | A numeric scalar to be passed to `mergeWindows`.
`equiweight` | A logical scalar indicating whether windows should be weighted so that each analysis contributes equally to the combined p-values.
`get.best` | A logical scalar indicating whether `getBestTest` or `getBestOverlaps` should be run.
`regions` | A GRanges class containing reference regions to overlap with the windows.
`merge.args` | Further arguments to pass to `mergeWindows`.
`overlap.args` | Further arguments to pass to `findOverlaps`.
`combine.args` | Further arguments to pass to `combineTests` or `combineOverlaps`.
`best.args` | Further arguments to pass to `getBestTest` or `getBestOverlaps`.

### Details

`mergeResultsList` calls `mergeWindowsList` to identify clusters of windows corresponding to regions. These clusters are used in `combineTests` and (optionally) `getBestTest` to obtain per-region statistics.

`overlapResultsList` calls `findOverlapsList` to identify all windows overlapping each reference region. These overlaps are used in `combineOverlaps` and (optionally) `getBestOverlaps`, where each set of overlapping windows for a reference region are used to define the latter's statistics.

Weighting is performed as described in `mergeWindowsList` and `findOverlapsList`. If `equiweight=FALSE`, weights are reported but are not used in the p-value calculations.

### Value

Both functions will return a DataFrame containing `regions`, a GRanges containing intervals of clustered windows (for `mergeResultsList`) or the input `regions` (for `overlapResultsList`); `combined`, the DataFrame containing combined statistics for each region; and `best`, the DataFrame containing statistics for the best window in each region.

The `metadata` of the DataFrame will contain `ranges`, a GRanges object containing the concatenated intervals from all elements of `ranges.list`; `tab`, a data.frame containing the combined results from all `tab.list`; and `weights`, a numeric vector of weights per window (for `mergeResultsList`) or per overlap (for `overlapsResultList`).

For `mergeResultsList`, the metadata will also contain `ids`, an integer vector specifying the cluster ID in the output `regions` for each interval in `ranges`.

For `overlapResultsList`, the metadata will also contain `overlaps`, a Hits object specifying the overlaps between the input `regions` (query) and `ranges`.

### Author(s)

Aaron Lun

### See Also

`mergeWindowsList`, `combineTests` and `getBestTest`, for the functions that actually do the work in `mergeResultsList`.

`findOverlapsList`, `combineOverlaps` and `getBestOverlaps`, for the functions that actually do the work in `overlapResultsList`.

### Examples

    # Making up some data.
    tab1 <- data.frame(logFC=rnorm(20), logCPM=rnorm(20), PValue=rbeta(20, 1, 2))
    gr1 <- GRanges("chrA", IRanges(sample(1000, 20), width=40))

    tab2 <- data.frame(logFC=rnorm(20), logCPM=rnorm(20), PValue=rbeta(20, 1, 2))
    gr2 <- GRanges("chrA", IRanges(sample(1000, 20), width=40))

    # Merging windows.
    (merge.out <- mergeResultsList(list(gr1, gr2), list(tab1, tab2), tol=1))
    merge.out$regions
    merge.out$combined

    # Overlapping windows with a reference.
    ref <- GRanges("chrA", IRanges(c(10, 500, 900), width=20))
    (olap.out <- overlapResultsList(list(gr1, gr2), list(tab1, tab2), regions=ref))
    olap.out$regions
    olap.out$combined

[Package csaw version 1.28.0 Index]