clusterWindows {csaw} | R Documentation

## Cluster DB windows into clusters

### Description

Clusters significant windows into clusters while controlling the cluster-level FDR.

### Usage

    clusterWindows(ranges, tab, target, pval.col=NULL, fc.col=NA, tol,
        ..., weights=NULL, grid.length=21, iterations=4)

### Arguments

`ranges` | A GRanges or RangedSummarizedExperiment object containing window coordinates.
`tab` | A data.frame of results with a `PValue` field for each window.
`target` | A numeric scalar indicating the desired cluster-level FDR.
`pval.col` | A string or integer scalar specifying the column of `tab` with the p-values.
`fc.col` | A string or integer scalar specifying the column of `tab` with the log-fold changes.
`tol, ...` | Arguments to be passed to `mergeWindows`.
`weights, grid.length, iterations` | Arguments to be passed to `controlClusterFDR`.

### Details

Windows are identified as DB based on the adjusted p-values in `tab`. Only these DB windows are then used directly for clustering via `mergeWindows`. This identifies DB regions consisting solely of DB windows. If `tol` is not specified, it is set to 100 bp by default and a warning is raised. If `fc.col` is used to specify the column of log-fold changes, clusters are formed according to the sign of the log-fold change in `mergeWindows`.

DB-based clustering is obviously not blind to the DB status, so standard methods for FDR control are not valid. Instead, post-hoc control of the cluster-level FDR is applied by using `controlClusterFDR`. This aims to control the cluster-level FDR at `target` (which is set to 0.05 if not specified). The aim is to provide some interpretable results when DB-blind clustering is not appropriate, e.g., for diffuse marks involving long stretches of the genome. Reporting each marked stretch in its entirety would be cumbersome, so this method allows the DB subintervals to be identified directly.

### Value

A named list similar to that reported by `mergeWindows`, with an integer vector of cluster IDs in `ids` and region coordinates of each cluster in `regions`. Non-significant windows that were not used to construct `regions` are marked with `NA` values in `ids`. An additional element `FDR` is also included, representing the estimate of the cluster-level FDR for the returned regions.

### Author(s)

Aaron Lun

### See Also

`mergeWindows`, `controlClusterFDR`

### Examples

    set.seed(10)
    x <- round(runif(100, 100, 1000))
    gr <- GRanges("chrA", IRanges(x, x+5))
    tab <- data.frame(PValue=rbeta(length(x), 1, 50), logFC=rnorm(length(x)))

    clusterWindows(gr, tab, target=0.05, tol=10)
    clusterWindows(gr, tab, target=0.05, tol=10, fc.col="logFC")

[Package csaw version 1.20.0 Index]