rdapply {IRanges} | R Documentation

## Applying over spaces

### Description

The `rdapply` function applies a user function over the spaces of a `RangedData`. The parameters to `rdapply` are collected into an instance of `RDApplyParams`, which is passed as the sole parameter to `rdapply`.

### Usage

    rdapply(x, ...)

### Arguments

`x` | The `RDApplyParams` instance, see below for how to make one.
`...` | Additional arguments for methods

### Details

The `rdapply` function is an attempt to facilitate the common operation of performing the same operation over each space (e.g. chromosome) in a `RangedData`. To facilitate a wide array of such tasks, the function takes a large number of options. The `RDApplyParams` class is meant to help manage this complexity. In particular, it facilitates experimentation through its support for incremental changes to parameter settings.

There are two `RangedData` settings that are required: the user `function` object and the `RangedData` over which it is applied. The rest of the settings determine what is actually passed to the user function and how the return value is processed before relaying it to the user. The following is the description and rationale for each setting.

`rangedData`
  REQUIRED. The `RangedData` instance over which `applyFun` is applied.
`applyFun`
  REQUIRED. The user `function` to be applied to each space in the `RangedData`. The function must expect the `RangedData` as its first parameter and also accept the parameters specified in `applyParams`.
`applyParams`
  The `list` of additional parameters to pass to `applyFun`. Usually empty.
`filterRules`
  The instance of `FilterRules` that is used to filter each subset of the `RangedData` passed to the user function. This is an efficient and convenient means for performing the same operation over different subsets of the data on a space-by-space basis. In particular, this avoids the need to store subsets of the entire `RangedData`. A common workflow is to invoke `rdapply` with one set of active filters, enable different filters, reinvoke `rdapply`, and compare the results.
`simplify`
  A scalar logical (`TRUE` or `FALSE`) indicating whether the `list` to be returned from `rdapply` should be simplified as by `sapply`. Defaults to `FALSE`.
`reducerFun`
  The `function` that is used to convert the `list` that would otherwise be returned from `rdapply` to something more convenient. The function should take the list as its first parameter and also accept the parameters specified in `reducerParams`. This is an alternative to the primitive behavior of the `simplify` option (so `simplify` must be `FALSE` if this option is set). The aim is to orthogonalize the `applyFun` operation (i.e. the statistics) from the data structure of the result.
`reducerParams`
  A `list` of additional parameters to pass to `reducerFun`. Can only be set if `reducerFun` is set. Usually empty.

### Value

By default a `list` holding the result of each invocation of the user function, but see details.

### Constructing an RDApplyParams object

  `RDApplyParams(rangedData, applyFun, applyParams, filterRules, simplify, reducerFun, reducerParams)`: Constructs a `RDApplyParams` object with each setting specified by the argument of the same name. See the Details section for more information.

### Accessors

In the following code snippets, `x` is an `RDApplyParams` object.

  `rangedData(x)`, `rangedData(x) <- value`: Get or set the `RangedData` instance over which `applyFun` is applied.
  `applyFun(x)`, `applyFun(x) <- value`: Get or set the user `function` to be applied to each space in the `RangedData`.
  `applyParams(x)`, `applyParams(x) <- value`: Get or set the `list` of additional parameters to pass to `applyFun`.
  `filterRules(x)`, `filterRules(x) <- value`: Get or set the instance of `FilterRules` that is used to filter each subset of the `RangedData` passed to the user function.
  `simplify(x)`, `simplify(x) <- value`: Get or set a a scalar logical (`TRUE` or `FALSE`) indicating whether the `list` to be returned from `rdapply` should be simplified as by `sapply`.
  `reducerFun(x)`, `reducerFun(x) <- value`: Get or set the `function` that is used to convert the `list` that would otherwise be returned from `rdapply` to something more convenient.
  `reducerParams(x)`, `reducerParams(x) <- value`: Get or set a `list` of additional parameters to pass to `reducerFun`.

### Author(s)

Michael Lawrence

### See Also

`RangedData`, `FilterRules`

### Examples

      ranges <- IRanges(c(1,2,3),c(4,5,6))
      score <- c(2L, 0L, 1L)
      rd <- RangedData(ranges, score, splitter = c("chr1","chr2","chr1"))

      ## a single function
      countrows <- function(rd) nrow(rd)
      params <- RDApplyParams(rd, countrows)
      rdapply(params) # list(chr1 = 2L, chr2 = 1L)

      ## with a parameter
      params <- RDApplyParams(rd, function(rd, x) nrow(rd)*x, list(x = 2))
      rdapply(params) # list(chr1 = 4L, chr2 = 2L)

      ## add a filter
      cutoff <- 0
      rules <- FilterRules(filter = score > cutoff)
      params <- RDApplyParams(rd, countrows, filterRules = rules)
      rdapply(params) # list(chr1 = 2L, chr2 = 0L)
      rules <- FilterRules(list(fun = function(rd) rd[["score"]] < 2),
                           filter = score > cutoff)
      params <- RDApplyParams(rd, countrows, filterRules = rules)
      rdapply(params) # list(chr1 = 1L, chr2 = 0L)
      active(filterRules(params))["filter"] <- FALSE
      rdapply(params) # list(chr1 = 1L, chr2 = 1L)

      ## simplify
      params <- RDApplyParams(rd, countrows, simplify = TRUE)
      rdapply(params) # c(chr1 = 2L, chr2 = 1L)

      ## reducing
      params <- RDApplyParams(rd, countrows, reducerFun = unlist,
                              reducerParams = list(use.names = FALSE))
      rdapply(params) ## c(2L, 1L)

[Package IRanges version 1.2.3 Index]