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 FilterRules 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 Vector.
x[[i]]: Extracts an expression or function via the same
interface as for List.
x[[i]] <- value: The same interface as for
List. 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
valuesFilterRules 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.
evalSeparately(expr, envir = parent.frame(), enclos = if
(is.list(envir) || is.pairlist(envir)) parent.frame() else
baseenv()): Evaluates separately each rule in 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 into
a logical matrix, with a column for each rule. This is
essentially the parallel evaluator, while eval is the
serial evaluator.
subsetByFilter(x, filter): Evaluates filter on
x and uses the result to subset x. The result
contains only the elements in x for which filter
evaluates to TRUE.
summary(object, subject):
Returns an integer vector with the number of elements
in subject that pass each rule in object, along with
a count of the elements that pass all filters.
Filter Closures
When a closure (function) is included as a filter in a
FilterRules object, it is converted to a FilterClosure,
which is currently nothing more than a marker class that extends
function. When a FilterClosure filter is extracted,
there are some accessors and utilities for manipulating it:
params: Gets a named list of the objects that are
present in the enclosing environment (without inheritance). This
assumes that a filter is constructed via a constructor function,
and the objects in the frame of the constructor (typically, the
formal arguments) are the parameters of the filter.
Author(s)
Michael Lawrence
See Also
FilterMatrix objects for storing the logical output of a set
of FilterRules objects.
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("promoters", "peaks", "introns")
filters <- FilterRules(filts)
## evaluation
df <- DataFrame(peaks = c(TRUE, TRUE, FALSE, FALSE),
promoters = c(TRUE, FALSE, FALSE, TRUE),
introns = c(TRUE, FALSE, FALSE, FALSE))
eval(filters, df)
fm <- evalSeparately(filters, df)
identical(filterRules(fm), filters)
summary(fm)
summary(fm, percent = TRUE)
fm <- evalSeparately(filters, df, serial = TRUE)
## 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)
Results
R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.
R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.
Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.
> library(S4Vectors)
Loading required package: stats4
Loading required package: BiocGenerics
Loading required package: parallel
Attaching package: 'BiocGenerics'
The following objects are masked from 'package:parallel':
clusterApply, clusterApplyLB, clusterCall, clusterEvalQ,
clusterExport, clusterMap, parApply, parCapply, parLapply,
parLapplyLB, parRapply, parSapply, parSapplyLB
The following objects are masked from 'package:stats':
IQR, mad, xtabs
The following objects are masked from 'package:base':
Filter, Find, Map, Position, Reduce, anyDuplicated, append,
as.data.frame, cbind, colnames, do.call, duplicated, eval, evalq,
get, grep, grepl, intersect, is.unsorted, lapply, lengths, mapply,
match, mget, order, paste, pmax, pmax.int, pmin, pmin.int, rank,
rbind, rownames, sapply, setdiff, sort, table, tapply, union,
unique, unsplit
Attaching package: 'S4Vectors'
The following objects are masked from 'package:base':
colMeans, colSums, expand.grid, rowMeans, rowSums
> png(filename="/home/ddbj/snapshot/RGM3/R_BC/result/S4Vectors/FilterRules-class.Rd_%03d_medium.png", width=480, height=480)
> ### Name: FilterRules-class
> ### Title: Collection of Filter Rules
> ### Aliases: class:expressionORfunction expressionORfunction-class
> ### expressionORfunction class:FilterRules FilterRules-class active
> ### active,FilterRules-method active<- active<-,FilterRules-method
> ### [,FilterRules-method [[<-,FilterRules-method subsetByFilter
> ### subsetByFilter,ANY,FilterRules-method
> ### append,FilterRules,FilterRules-method c,FilterRules-method
> ### eval,FilterRules,ANY-method evalSeparately
> ### evalSeparately,FilterRules-method FilterRules
> ### summary,FilterRules-method params params,FilterClosure-method
> ### coerce,standardGeneric,FilterClosure-method
> ### coerce,function,FilterClosure-method show,FilterClosure-method
> ### Keywords: classes methods
>
> ### ** 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
peaks promoters
TRUE 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
peaks promoters find_eboxes
FALSE FALSE 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("promoters", "peaks", "introns")
> filters <- FilterRules(filts)
>
> ## evaluation
> df <- DataFrame(peaks = c(TRUE, TRUE, FALSE, FALSE),
+ promoters = c(TRUE, FALSE, FALSE, TRUE),
+ introns = c(TRUE, FALSE, FALSE, FALSE))
> eval(filters, df)
[1] TRUE FALSE FALSE FALSE
> fm <- evalSeparately(filters, df)
> identical(filterRules(fm), filters)
[1] TRUE
> summary(fm)
<initial> promoters peaks introns <final>
4 2 2 1 1
> summary(fm, percent = TRUE)
<initial> promoters peaks introns <final>
1.00 0.50 0.50 0.25 0.25
> fm <- evalSeparately(filters, df, serial = TRUE)
>
> ## 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)
>
>
>
>
>
> dev.off()
null device
1
>