IRanges (version 2.0.1)

rdapply: 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

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.

iteratorFun(x), iteratorFun(x) <- value: Get or set the function used for applying over the RangedData.

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.

iteratorFun

The function used for applying over the RangedData. By default, this is lapply, but it could also be a specialized function, like mclapply.

See Also

RangedData, FilterRules

Examples

  ranges <- IRanges(c(1,2,3),c(4,5,6))
  score <- c(2L, 0L, 1L)
  rd <- RangedData(ranges, score, space = 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)