R/eply.R

In wlandau-lilly/eply: Apply a Function Over Expressions

#' @title Function \code{eply}
#' @description Apply a function over a data frame of quoted expressions.
#' Parallel execution is available using the \code{.split} and \code{.tasks} arguments.
#' @seealso \code{\link{evals}}, \code{\link{help_eply}}
#' @export
#' @details \code{.fun} is a function, and \code{.expr} is a data frame.
#' In \code{.expr}, each row stands for a single call to \code{.fun}, and each
#' column stands for an argument. Each element is a quoted expression that
#' uses the data in \code{.with} during evaluation.
#' When \code{\link{eply}} is called on each row, the expressions
#' are evaluated on \code{.with},
#' and the results are given to \code{.fun} as function arguments.
#' The column names of \code{.expr} must
#' contain the argument names of \code{.fun}.
#' With \code{.tasks} and \code{.split}, Mac and Linux users can
#' distribute the work over multiple parallel tasks. See the vignette for an
#' example (\code{vignette("eply")}).
#' @return a list or vector of return values of \code{.fun}.
#' @param .fun function to evaluate.
#' @param .expr data frame of quoted expressions. Column names must
#' contain the argument names of \code{.fun}.
#' @param .with list, data frame, or environment with the
#' data accessible to \code{.expr}
#' @examples
#' # Get an example data frame of commands that evaluate to function arguments.
#' .expr <- example.expr()
#' .fun <- example.fun # Get an example collection of functions.
#' # Get an example list of supporting data. Could be an environment.
#' .with <- example.with()
#' # Row-by-row, evaluate the code in .expr and feed the results to the function.
#' eply(.fun = .fun, .expr = .expr, .with = .with)
eply <- function(.fun, .expr, .with = parent.frame()) {
  checks_eply(.fun = .fun, .expr = .expr, .with = .with)
  force(.with)
  subset(.expr, select = formalArgs(.fun)) %>%
    apply(1, function(x) {
      .args <- vevals(x, .with = .with)
      do.call(.fun, .args)
    })
}