\HeaderA{rdapply}{Applying over spaces}{rdapply}
\aliasA{applyFun}{rdapply}{applyFun}
\aliasA{applyFun,RDApplyParams-method}{rdapply}{applyFun,RDApplyParams.Rdash.method}
\aliasA{applyFun<\Rdash}{rdapply}{applyFun<.Rdash.}
\aliasA{applyFun<-,RDApplyParams-method}{rdapply}{applyFun<.Rdash.,RDApplyParams.Rdash.method}
\aliasA{applyParams}{rdapply}{applyParams}
\aliasA{applyParams,RDApplyParams-method}{rdapply}{applyParams,RDApplyParams.Rdash.method}
\aliasA{applyParams<\Rdash}{rdapply}{applyParams<.Rdash.}
\aliasA{applyParams<-,RDApplyParams-method}{rdapply}{applyParams<.Rdash.,RDApplyParams.Rdash.method}
\aliasA{filterRules}{rdapply}{filterRules}
\aliasA{filterRules,RDApplyParams-method}{rdapply}{filterRules,RDApplyParams.Rdash.method}
\aliasA{filterRules<\Rdash}{rdapply}{filterRules<.Rdash.}
\aliasA{filterRules<-,RDApplyParams-method}{rdapply}{filterRules<.Rdash.,RDApplyParams.Rdash.method}
\aliasA{rangedData}{rdapply}{rangedData}
\aliasA{rangedData,RDApplyParams-method}{rdapply}{rangedData,RDApplyParams.Rdash.method}
\aliasA{rangedData<\Rdash}{rdapply}{rangedData<.Rdash.}
\aliasA{rangedData<-,RDApplyParams-method}{rdapply}{rangedData<.Rdash.,RDApplyParams.Rdash.method}
\aliasA{rdapply,RDApplyParams-method}{rdapply}{rdapply,RDApplyParams.Rdash.method}
\aliasA{RDApplyParams}{rdapply}{RDApplyParams}
\aliasA{RDApplyParams-class}{rdapply}{RDApplyParams.Rdash.class}
\aliasA{reducerFun}{rdapply}{reducerFun}
\aliasA{reducerFun,RDApplyParams-method}{rdapply}{reducerFun,RDApplyParams.Rdash.method}
\aliasA{reducerFun<\Rdash}{rdapply}{reducerFun<.Rdash.}
\aliasA{reducerFun<-,RDApplyParams-method}{rdapply}{reducerFun<.Rdash.,RDApplyParams.Rdash.method}
\aliasA{reducerParams}{rdapply}{reducerParams}
\aliasA{reducerParams,RDApplyParams-method}{rdapply}{reducerParams,RDApplyParams.Rdash.method}
\aliasA{reducerParams<\Rdash}{rdapply}{reducerParams<.Rdash.}
\aliasA{reducerParams<-,RDApplyParams-method}{rdapply}{reducerParams<.Rdash.,RDApplyParams.Rdash.method}
\aliasA{simplify}{rdapply}{simplify}
\aliasA{simplify,RDApplyParams-method}{rdapply}{simplify,RDApplyParams.Rdash.method}
\aliasA{simplify<\Rdash}{rdapply}{simplify<.Rdash.}
\aliasA{simplify<-,RDApplyParams-method}{rdapply}{simplify<.Rdash.,RDApplyParams.Rdash.method}
\keyword{classes}{rdapply}
\keyword{methods}{rdapply}
\begin{Description}\relax
The \code{rdapply} function applies a user function over
the spaces of a \code{\LinkA{RangedData}{RangedData.Rdash.class}}. The parameters to
\code{rdapply} are collected into an instance of \code{RDApplyParams},
which is passed as the sole parameter to \code{rdapply}.
\end{Description}
\begin{Usage}
\begin{verbatim}
rdapply(x, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] The \code{RDApplyParams} instance, see below for how to
make one.
\item[\code{...}] Additional arguments for methods
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \code{rdapply} function is an attempt to facilitate the common
operation of performing the same operation over each space
(e.g. chromosome) in a \code{RangedData}. To facilitate a wide array
of such tasks, the function takes a large number of options. The
\code{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 \code{RangedData} settings that are required: the
user \code{function} object and the \code{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.

\describe{
\item[\code{rangedData}] \strong{REQUIRED}.
The \code{RangedData} instance over which \code{applyFun} is
applied. 

\item[\code{applyFun}] \strong{REQUIRED}.
The user \code{function} to be applied to each space in the
\code{RangedData}. The function must expect the \code{RangedData} as its
first parameter and also accept the parameters specified in
\code{applyParams}.

\item[\code{applyParams}] The \code{list} of additional parameters to pass to
\code{applyFun}. Usually empty.

\item[\code{filterRules}] The instance of \code{\LinkA{FilterRules}{FilterRules.Rdash.class}} that is used to
filter each subset of the \code{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 \code{RangedData}. A common workflow is to
invoke \code{rdapply} with one set of active filters, enable
different filters, reinvoke \code{rdapply}, and compare the
results.

\item[\code{simplify}] A scalar logical (\code{TRUE} or \code{FALSE}) indicating whether
the \code{list} to be returned from \code{rdapply} should be
simplified as by \code{\LinkA{sapply}{sapply}}. Defaults to \code{FALSE}.

\item[\code{reducerFun}] The \code{function} that is used to convert the \code{list} that
would otherwise be returned from \code{rdapply} to something more
convenient. The function should take the list as its first
parameter and also accept the parameters specified in
\code{reducerParams}. This is an alternative to the
primitive behavior of the \code{simplify} option (so
\code{simplify} must be \code{FALSE} if this option is set). The
aim is to orthogonalize the \code{applyFun} operation (i.e. the
statistics) from the data structure of the result.

\item[\code{reducerParams}] A \code{list} of additional parameters to pass to \code{reducerFun}.
Can only be set if \code{reducerFun} is set. Usually empty.

}
\end{Details}
\begin{Value}
By default a \code{list} holding the result of each invocation of the
user function, but see details.
\end{Value}
\begin{Section}{Constructing an RDApplyParams object}
\describe{
\item[] \code{RDApplyParams(rangedData, applyFun, applyParams,
        filterRules, simplify, reducerFun, reducerParams)}:
Constructs a \code{RDApplyParams} object with each setting
specified by the argument of the same name. See the Details section
for more information.

}
\end{Section}
\begin{Section}{Accessors}
In the following code snippets, \code{x} is an \code{RDApplyParams}
object.

\describe{
\item[] \code{rangedData(x)}, \code{rangedData(x) <- value}: Get or set the
\code{RangedData} instance over which \code{applyFun} is applied.

\item[] \code{applyFun(x)}, \code{applyFun(x) <- value}: Get or set the user
\code{function} to be applied to each space in the \code{RangedData}.

\item[] \code{applyParams(x)}, \code{applyParams(x) <- value}: Get
or set the \code{list} of additional parameters to pass to
\code{applyFun}.

\item[] \code{filterRules(x)}, \code{filterRules(x) <- value}: Get
or set the instance of \code{\LinkA{FilterRules}{FilterRules.Rdash.class}} that is used to
filter each subset of the \code{RangedData} passed to the user
function. 

\item[] \code{simplify(x)}, \code{simplify(x) <- value}: Get or set a
a scalar logical (\code{TRUE} or \code{FALSE}) indicating whether
the \code{list} to be returned from \code{rdapply} should be
simplified as by \code{\LinkA{sapply}{sapply}}.

\item[] \code{reducerFun(x)}, \code{reducerFun(x) <- value}: Get or set the
\code{function} that is used to convert the \code{list} that would
otherwise be returned from \code{rdapply} to something more convenient.

\item[] \code{reducerParams(x)}, \code{reducerParams(x) <- value}:
Get or set a \code{list} of additional parameters to pass to
\code{reducerFun}.

}
\end{Section}
\begin{Author}\relax
Michael Lawrence
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{RangedData}{RangedData.Rdash.class}}, \code{\LinkA{FilterRules}{FilterRules.Rdash.class}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  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)
\end{ExampleCode}
\end{Examples}

