FilterRules-class          package:IRanges          R Documentation

Collection of Filter Rules

Description:

     A 'FilterRules' object is a collection of filter rules, which can
     be either 'expression' or 'function' objects. Rules can be
     disabled/enabled individually, facilitating experimenting with
     different combinations of filters.

Details:

     It is common to split a dataset into subsets during data analysis.
     When data is large, however, representing subsets (e.g. by logical
     vectors) and storing them as copies might become too costly in
     terms of space. The 'FilterRules' class represents subsets as
     lightweight 'expression' and/or 'function' objects. Subsets can
     then be calculated when needed (on the fly). This avoids copying
     and storing a large number of subsets. Although it might take
     longer to frequently recalculate a subset, it often is a
     relatively fast operation and the space savings tend to be more
     than worth it when data is large.

     Rules may be either expressions or functions. Evaluating an
     expression or invoking a function should result in a logical
     vector. Expressions are often more convenient, but functions (i.e.
     closures) are generally safer and more powerful, because the user
     can specify the enclosing environment. If a rule is an expression,
     it is evaluated inside the 'envir' argument to the 'eval' method
     (see below). If a function, it is invoked with 'envir' as its only
     argument. See examples.

Accessor methods:

     In the code snippets below, 'x' is a 'RangedData' object.


      'active(x)': Get the logical vector of length 'length(x)', where
          'TRUE' for an element indicates that the corresponding rule
          in 'x' is active (and inactive otherwise). Note that
          'names(active(x))' is equal to 'names(x)'.

      'active(x) <- value': Replace the active state of the filter
          rules. If 'value' is a logical vector, it should be of length
          'length(x)' and indicate which rules are active. Otherwise,
          it can be either numeric or character vector, in which case
          it sets the indicated rules (after dropping NA's) to active
          and all others to inactive. See examples.

Constructor:


      'FilterRules(exprs = list(), ..., active = TRUE)': Constructs a
          'FilterRules' with the rules given in the list 'exprs' or in
          '...'. The initial active state of the rules is given by
          'active', which is recycled as necessary. Elements in 'exprs'
          may be either character (parsed into an expression), a
          language object (coerced to an expression), an expression, or
          a function that takes at least one argument. *IMPORTANTLY*,
          all arguments in '...' are *'quote()'*'d and then coerced to
          an expression. So, for example, character data is only parsed
          if it is a literal. The names of the filters are taken from
          the names of 'exprs' and '...', if given. Otherwise, the
          character vectors take themselves as their name and the
          others are deparsed (before any coercion). Thus, it is
          recommended to always specify meaningful names. In any case,
          the names are made valid and unique.


Subsetting and Replacement:

     In the code snippets below, 'x' is a 'FilterRules' object.


      'x[i]': Subsets the filter rules using the same interface as for
          'Sequence'.

      'x[[i]]': Extracts an expression or function via the same
          interface as for 'Sequence'.

      'x[[i]] <- value': The same interface as for 'Sequence'. The
          default active state for new rules is 'TRUE'.


Combining:

     In the code snippets below, 'x' is a 'FilterRules' object.


      'append(x, values, after = length(x))': Appends the 'values'
          'FilterRules' instance onto 'x' at the index given by
          'after'.

      'c(x, ..., recursive = FALSE)': Concatenates the 'FilterRule'
          instances in '...' onto the end of 'x'.


Evaluating:


      'eval(expr, envir = parent.frame(), enclos = if (is.list(envir)
          || is.pairlist(envir)) parent.frame() else baseenv())': 
          Evaluates a 'FilterRules' instance (passed as the 'expr'
          argument). Expression rules are evaluated in 'envir', while
          function rules are invoked with 'envir' as their only
          argument. The evaluation of a rule should yield a logical
          vector. The results from the rule evaluations are combined
          via the AND operation (i.e. '&') so that a single logical
          vector is returned from 'eval'.


Author(s):

     Michael Lawrence

See Also:

     'rdapply', which accepts a 'FilterRules' instance to filter each
     space before invoking the user function.

Examples:

       ## constructing a FilterRules instance

       ## an empty set of filters
       filters <- FilterRules()
       
       ## as a simple character vector
       filts <- c("peaks", "promoters")
       filters <- FilterRules(filts)
       active(filters) # all TRUE

       ## with functions and expressions
       filts <- list(peaks = expression(peaks), promoters = expression(promoters),
                     find_eboxes = function(rd) rep(FALSE, nrow(rd)))
       filters <- FilterRules(filts, active = FALSE)
       active(filters) # all FALSE

       ## direct, quoted args (character literal parsed)
       filters <- FilterRules(under_peaks = peaks, in_promoters = "promoters")
       filts <- list(under_peaks = expression(peaks),
                     in_promoters = expression(promoters))

       ## specify both exprs and additional args
       filters <- FilterRules(filts, diffexp = de)

       filts <- c("peaks", "promoters", "introns")
       filters <- FilterRules(filts)

       ## set the active state directly
       
       active(filters) <- FALSE # all FALSE
       active(filters) <- TRUE # all TRUE
       active(filters) <- c(FALSE, FALSE, TRUE)
       active(filters)["promoters"] <- TRUE # use a filter name
       
       ## toggle the active state by name or index
       
       active(filters) <- c(NA, 2) # NA's are dropped
       active(filters) <- c("peaks", NA) 

