rdapply               package: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, 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)

