subsetRegionsBySignal {BRGenomics} | R Documentation

## Subset regions of interest by quantiles of overlapping signal

### Description

A convenience function to subset regions of interest by the amount of signal they contain, according to their quantile (i.e. their signal ranks).

### Usage

    subsetRegionsBySignal(
      regions.gr,
      dataset.gr,
      quantiles = c(0.5, 1),
      field = "score",
      order.by.rank = FALSE,
      density = FALSE,
      keep.signal = FALSE,
      expand_ranges = FALSE
    )

### Arguments

`regions.gr` | A GRanges object containing regions of interest.
`dataset.gr` | A GRanges object in which signal is contained in metadata (typically in the "score" field).
`quantiles` | A value pair giving the lower quantile and upper quantile of regions to keep. Regions with signal quantiles below the lower quantile are removed, and likewise for regions with signal quantiles above the upper quantile. Quantiles must be in range `(0, 1)`. An empty GRanges object is returned if the lower quantile is set to `1` or if the upper quantile is set to `0`.
`field` | The metadata field of `dataset.gr` to be counted, typically "score".
`order.by.rank` | If `TRUE`, the output regions are sorted based on the amount of overlapping signal (in decreasing order). If `FALSE` (the default), genes are sorted by their positions.
`density` | A logical indicating whether signal counts should be normalized to the width (chromosomal length) of ranges in `regions.gr`. By default, no length normalization is performed.
`keep.signal` | Logical indicating if signal counts should be kept. If set to `TRUE`, the signal for each range (length-normalized if `density = TRUE`) are kept as a new `Signal` metadata column in the output GRanges object.
`expand_ranges` | Logical indicating if ranges in `dataset.gr` should be treated as descriptions of single molecules (`FALSE`), or if ranges should be treated as representing multiple adjacent positions with the same signal (`TRUE`). See `getCountsByRegions`.

### Value

A GRanges object of length `length(regions.gr) * (upper_quantile - lower_quantile)`.

### Author(s)

Mike DeBerardine

### See Also

`getCountsByRegions`

### Examples

    data("PROseq") # load included PROseq data
    data("txs_dm6_chr4") # load included transcripts

    txs_dm6_chr4

    #--------------------------------------------------#
    # get the top 50% of transcripts by signal
    #--------------------------------------------------#

    subsetRegionsBySignal(txs_dm6_chr4, PROseq)

    #--------------------------------------------------#
    # get the middle 50% of transcripts by signal
    #--------------------------------------------------#

    subsetRegionsBySignal(txs_dm6_chr4, PROseq, quantiles = c(0.25, 0.75))

    #--------------------------------------------------#
    # get the top 10% of transcripts by signal, and sort them by highest signal
    #--------------------------------------------------#

    subsetRegionsBySignal(txs_dm6_chr4, PROseq, quantiles = c(0.9, 1),
                          order.by.rank = TRUE)

    #--------------------------------------------------#
    # remove the most extreme 10% of regions, and keep scores
    #--------------------------------------------------#

    subsetRegionsBySignal(txs_dm6_chr4, PROseq, quantiles = c(0.05, 0.95),
                          keep.signal = TRUE)

[Package BRGenomics version 1.4.0 Index]