consolidateWindows {csaw} | R Documentation

## Consolidate window sizes

### Description

Consolidate windows of different sizes into a common set of clusters.

### Usage

    consolidateWindows(data.list, equiweight=TRUE, merge.args=list(),
        region=NULL, overlap.args=list(), sign.list=NULL)

### Arguments

`data.list` | A list of RangedSummarizedExperiment and/or GRanges objects.
`equiweight` | A logical scalar indicating whether equal weighting from each window size should be enforced.
`merge.args` | A named list of parameters to pass to `mergeWindows`.
`region` | A GRanges object specifying regions of interest for overlapping with windows.
`overlap.args` | A named list of parameters to pass to `findOverlaps`.
`sign.list` | A list of logical vectors, where each vector corresponds to and is of the same length as an object in `data.list`. Each value of the vector should indicate whether the log-fold change is positive for the corresponding window.

### Details

This function merges windows of differing sizes, generated by multiple calls to `windowCounts` using different `width` values. If `region=NULL`, windows of all sizes are clustered together through `mergeWindows`, using a default tolerance of 100 bp. Otherwise, clusters are defined by overlapping windows of all sizes to `region` using `findOverlaps`, where each entry of `region` defines a cluster.

The aim is to pass the output of this function to `consolidateTests` or `consolidateOverlaps` to consolidate statistics across window sizes. This will provide comprehensive detection of DB at a range of spatial resolutions. However, this requires some care to balance the contribution of analyses with different window sizes to the combined p-value. This is achieved by weighting each window and using the weights in downstream functions.

By default, we set `equiweight=TRUE` to offset the differences in the number of windows of each size per cluster. The weight of each window is inversely proportional to the number of windows of the same size within a given cluster. If `region!=NULL`, the weight of each overlap is inversely proportional to the number of overlaps involving windows of the same size to the given region. This ensures that the combined p-value is not fully determined by numerous small windows within a cluster.

The signs of the log-fold change can be specified using `sign.list`. This should be a list of logical vectors indicating whether the log-fold changes for each set of windows of `data.list` are positive. We do not recommend using this for routine analyses - see `?mergeWindows` for details.

### Value

If `region=NULL`, a named list is returned containing:

`id`:

  A list of integer vectors, where each vector corresponds to an object in `data.list`. The entries of the vector specify the cluster to which each window of that object is assigned.

`weight`:

  A list of numeric vectors, where each vector corresponds to a vector in `id`. The entries of the vector specify the weight of the corresponding windows.

`region`:

  A GRanges object containing the genomic coordinates of the clusters of merged windows.

If `region` is not `NULL`, a named list is returned containing:

`olap`:

  A list of Hits object, where each object corresponds to an object in `data.list`. Each Hits object contains the overlaps between the input `regions` (query) and the windows in the corresponding object in `data.list` (subject).

`weight`:

  A list of numeric vectors, where each vector corresponds to a Hits object in `olap`. The entries of the vector specify the per-overlap weight of the corresponding windows.

### Author(s)

Aaron Lun

### See Also

`windowCounts`, `mergeWindows`, `findOverlaps`, `consolidateTests`, `consolidateOverlaps`

### 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)

    # Consolidating.
    cons <- consolidateWindows(list(low, med, high), merge.args=list(tol=100))
    str(cons$id)
    str(cons$weights)
    cons$region

    # 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)
    str(cons$id)
    str(cons$weights)

[Package csaw version 1.18.0 Index]