Commit b0f5d833 authored by Alasdair Hunter's avatar Alasdair Hunter
Browse files

Update documentation

parent 35c234f9
......@@ -5,7 +5,7 @@ Authors@R: c(
person("BSC-CNS", role = c("aut", "cph")),
person("Alasdair", "Hunter", , "alasdair.hunter@bsc.es", role = c("aut", "cre")),
person("Nicolau", "Manubens", , "nicolau.manubens@bsc.es", role = "aut"))
Description: The base apply function and its variants, as well as the related functions in the 'plyr' package, typically apply a function to a single object, or a list of unidimensional objects in the case of the mapply function. The 'multiApply' package extends this paradigm to functions taking multiple unidimensional or multidimensional objects (vectors, arrays or other objects with a dimensions attribute) as input, which can have different numbers of dimensions as well as different dimension lengths. The multiApply package also allows the user to specify which dimensions of each array (or matrix) the function is to be applied over. The user could replicate this functionality by combining for loops with calls to apply and abind::abind, but using multiApply::Apply this is straightforward, and the use of multiple cores is simplified.
Description: The base apply function and its variants, as well as the related functions in the 'plyr' package, typically apply user-defined functions to a single argument (or a list of vectorized arguments in the case of mapply). The 'multiApply' package extends this paradigm to functions taking a list of multiple unidimensional or multidimensional arguments (or combinations thereof) as input, which can have different numbers of dimensions as well as different dimension lengths.
Depends:
R (>= 3.2.0)
Imports:
......
#' Wrapper for Applying Atomic Functions to Arrays.
#'
#' A wrapper for applying a function, taking one or more arrays (or vectors or matrices), potentially with different dimensions. The user can input one or more arrays, and specify the dimensions of each of the arrays over which the function should be looped. This is an extension of the apply paradigm to the case where the data being considered are distributed across multiple numeric objects.
#' @param data A single numeric object (vector, matrix or array) or a list of numeric objects. They must be in the same order as expected by AtomicFun.
#' The Apply function is an extension of the mapply function, which instead of taking lists of unidimensional objects as input, takes lists of multidimensional objects as input, which may have different numbers of dimensions and dimension lengths. The user can specify which dimensions of each array (or matrix) the function is to be applied over with the margins option.
#' @param data A single object (vector, matrix or array) or a list of objects. They must be in the same order as expected by AtomicFun.
#' @param margins List of vectors containing the margins for the input objects to be split by. Or, if there is a single vector of margins specified and a list of objects in data, then the single set of margins is applied over all objects. These vectors can contain either integers specifying the dimension position, or characters corresponding to the dimension names. If both margins and inverse_margins are specified, margins takes priority over inverse_margins.
#' @param AtomicFun Function to be applied to the arrays.
#' @param ... Additional arguments to be used in the AtomicFun.
#' @param inverse_margins List of vectors containing the dimensions to be input into AtomicFun for each of the objects in the data. These vectors can contain either integers specifying the dimension position, or characters corresponding to the dimension names. If both margins and inverse_margins are specified, margins takes priority over inverse_margins.
#' @param parallel Logical, should the function be applied in parallel.
#' @param ncores The number of cores to use for parallel computation.
#' @details When using a single numeric object as input, Apply is almost identical to the apply function. For multiple input objects, the output array will have dimensions equal to the dimensions specified in 'margins'.
#' @details When using a single object as input, Apply is almost identical to the apply function. For multiple input objects, the output array will have dimensions equal to the dimensions specified in 'margins'.
#' @return Array or matrix or vector resulting from AtomicFun.
#' @references Wickham, H (2011), The Split-Apply-Combine Strategy for Data Analysis, Journal of Statistical Software.
#' @export
......@@ -66,7 +66,7 @@ Apply <- function(data, margins = NULL, AtomicFun, ..., inverse_margins = NULL,
}
names <- names(dim(data[[1]]))[margins[[1]]]
input <- list()
f <- splat(get(AtomicFun))
splatted_f <- splat(get(AtomicFun))
if (!is.null(margins)) {
.isolate <- function(data, margin_length, drop = TRUE) {
eval(dim(environment()$data))
......@@ -92,7 +92,7 @@ Apply <- function(data, margins = NULL, AtomicFun, ..., inverse_margins = NULL,
registerDoParallel(ncores)
}
WrapperFun <- llply(1 : i_max, function(i)
sapply((k * i - (k - 1)) : (k * i), function(x) f(lapply(input, `[[`, x),...), simplify = FALSE),
sapply((k * i - (k - 1)) : (k * i), function(x) splatted_f(lapply(input, `[[`, x),...), simplify = FALSE),
.parallel = parallel)
if (parallel == TRUE) {
registerDoSEQ()
......@@ -105,9 +105,11 @@ Apply <- function(data, margins = NULL, AtomicFun, ..., inverse_margins = NULL,
dim(data[[1]])[margins[[1]]]))
}
} else {
WrapperFun <- f(data, ...)
WrapperFun <- splatted_f(data, ...)
}
if (!is.null(dim(WrapperFun))) {
names(dim(WrapperFun)) <- c(AtomicFun, names)
}
names(dim(WrapperFun)) <- c(AtomicFun, names)
out <- WrapperFun
}
......
......@@ -5,10 +5,10 @@
\title{Wrapper for Applying Atomic Functions to Arrays.}
\usage{
Apply(data, margins = NULL, AtomicFun, ..., inverse_margins = NULL, parallel = FALSE,
ncores = NULL)
ncores = NULL)
}
\arguments{
\item{data}{A single numeric object (vector, matrix or array) or a list of numeric objects. They must be in the same order as expected by AtomicFun.}
\item{data}{A single object (vector, matrix or array) or a list of objects. They must be in the same order as expected by AtomicFun.}
\item{margins}{List of vectors containing the margins for the input objects to be split by. Or, if there is a single vector of margins specified and a list of objects in data, then the single set of margins is applied over all objects. These vectors can contain either integers specifying the dimension position, or characters corresponding to the dimension names. If both margins and inverse_margins are specified, margins takes priority over inverse_margins.}
......@@ -26,11 +26,10 @@ Apply(data, margins = NULL, AtomicFun, ..., inverse_margins = NULL, parallel = F
Array or matrix or vector resulting from AtomicFun.
}
\description{
When using a single numeric object as input, Apply is almost identical to the apply function. For multiple input objects, the output array
will have dimensions equal to the dimensions specified in 'margins'.
Takes lists of multidimensional objects as input, which may have different numbers of dimensions and dimension lengths. The user can specify which dimensions of each array (or matrix) the function is to be applied over with the margins option.
}
\details{
A user can apply a function that receives 1 or more numeric objects as input, each with a different number of dimensions, and returns as a result a single array with any number of dimensions.
A user can apply a function that receives 1 or more objects as input, each with a different number of dimensions, and returns as a result a single array with any number of dimensions.
}
\examples{
#Change in the rate of exceedance for two arrays, with different
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment