Result wrappers {csaw} | R Documentation

## Wrappers to get region-level results

### Description

Convenience wrappers around lower-level functions to easily obtain region-level results from window statistics.

### Usage

    mergeResults(ranges, tab=mcols(ranges), tol, get.best=TRUE,
        merge.args=list(), combine.args=list(), best.args=list())

    overlapResults(ranges, tab=mcols(ranges), regions, get.best=TRUE,
        overlap.args=list(), combine.args=list(), best.args=list())

### Arguments

`ranges` | A GRanges or RangedSummarizedExperiment containing genomic intervals, usually for windows.
`tab` | A data.frame of differential binding results with one row per interval in `ranges`, to be passed to `combineTests` or `combineOverlaps`.
`tol` | A numeric scalar to be passed to `mergeWindows`.
`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

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

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

These wrapper functions are simply for convenience. No other work is performed and so users are free to call the individual functions separately.

### Value

`mergeResults` will return a DataFrame containing `regions`, the GRanges generated by clustering windows into regions; `combined`, the DataFrame containing combined statistics for each clustered region; and `best`, the DataFrame containing statistics for the best window in each clustered region. The metadata contains `ids`, an integer vector of cluster IDs for `ranges` from `mergeWindows`.

`overlapResults` will return a DataFrame containing `regions`, the same as the input GRanges of the same name; `combined`, the DataFrame containing combined statistics for each regionserence region; and `best`, the DataFrame containing statistics for the best window in each regionserence region. The metadata contains `overlaps`, a Hits object specifying the overlaps from `findOverlaps`.

### Author(s)

Aaron Lun

### See Also

`mergeWindows`, `combineTests` and `getBestTest`, for the functions that actually do the work in `mergeResults`.

`findOverlaps`, `combineOverlaps` and `getBestOverlaps`, for the functions that actually do the work in `overlapResults`.

### Examples

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

    # Merging windows.
    (merge.out <- mergeResults(gr, tab, tol=1))
    merge.out$merged
    merge.out$combined

    # Overlapping windows with a regionserence.
    regions <- GRanges("chrA", IRanges(c(10, 500, 900), width=20))
    (olap.out <- overlapResults(gr, tab, regions=regions))
    olap.out$regions
    olap.out$combined

[Package csaw version 1.26.0 Index]