R/RcppExports.R

Defines functions arrApply

Documented in arrApply

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' High Performance Variant of apply()
#'
#'  High performance variant of apply() for a fixed set of functions.
#'  Considerable speedup is a trade-off for universality, user defined
#'  functions cannot be used with arrApply. However, 20 most currently employed
#'  functions are available for usage. They can be divided in three types:
#'  reducing functions (like mean(), sum() etc., giving a scalar when applied to a vector),
#'  mapping function (like normalise(), cumsum() etc., giving a vector of the same length
#'  as the input vector) and finally, vector reducing function (like diff() which produces
#'  result vector of a length different from the length of input vector).
#'  Optional or mandatory additional arguments required by some functions
#'  (e.g. norm type for norm() or normalise() functions) can be
#'  passed as named arguments in '...'.
#' 
#' The following functions can be used as argument 'fun' (brackets
#' [] indicate additional parameters that can be passed in '...'):
#'  - reducing functions: sum(), prod(), all(), any(), min(), max(),
#'    mean(), median(), sd() [norm_type], var() [norm_type], norm() [p],
#'    trapz() [x] (trapezoidal integration with respect to spacing in x,
#'    if x is provided, otherwise unit spacing is used);
#'  - mapping functions: normalise() [p], cumsum(), cumprod(), multv() [v]
#'    (multiply a given dimension by a vector v, term by term), divv() [v]
#'    (divide by a vector v), addv() [v] (add a vector v), subv() [v] (subtract
#'    a vector v);
#'  - vector reducing function: diff() [k].
#' 
#' RcppArmadillo is used to do the job in very fast way but it comes at price
#' of not allowing NA in the input numeric array.
#' Vectors are allowed at input. They are considered as arrays of dimension 1.
#' So in this case, \code{idim} can only be 1.
#' 
#' 
#' @param arr numeric array of arbitrary dimension
#' @param idim integer, dimension number along which a function must be applied
#' @param fun character string, function name to be applied
#' @param ... additional named parameters. Optional parameters can be helpful for
#'    the following functions:
#'       sd(), var() [norm_type: 0 normalisation using N-1 entries (default);
#'          1 normalisation using N entries];
#'       norm() [p: integer >= 1 (default=2) or one of "-inf", "inf", "fro".]
#'       normalise() [p: integer >= 1, default=2]
#'       diff() [k: integer >= 1 (default=1) number of recursive application of diff().
#'          The size of idim-th dimension will be reduced by k.]
#'       trapz() [x: numerical vector of the same length as idim-th size of arr]
#'    Mandatory parameter:
#'       multv(), divv(), addv(), subv() [v: numerical vector of the same
#'          length as idim-th size of arr]
#'
#' @return output array of dimension cut by 1 (the idim-th dimension
#'    will disappear for reducing functions) or of the same dimension
#'    as the input arr for mapping and vector reducing
#'    functions. For vector reducing functions, the idim-th dimension
#'    will be different from idim-th dimension of arr.
#'    The type of result (numeric or logical) depends on the function applied,
#'    logical for all() and any(), numerical -- for all other functions.
#' 
#' @examples
#'  arr=matrix(1:12, 3, 4)
#'  v1=arrApply(arr, 2, "mean")
#'  v2=rowMeans(arr)
#'  stopifnot(all(v1==v2))
#'  
#'  arr=array(1:24, dim=2:4) # dim(arr)=c(2, 3, 4)
#'  mat=arrApply(arr, 2, "prod") # dim(mat)=c(2, 4), the second dimension is cut out
#'  stopifnot(all(mat==apply(arr, c(1, 3), prod)))
#' 
#' @author Serguei Sokol <sokol at insa-toulouse.fr>
#' 
#' @export
arrApply <- function(arr, idim = 1L, fun = "sum", ...) {
    dots = list(...)
    .Call('arrApply_arrApply', PACKAGE = 'arrApply', arr, idim, fun, dots)
}

Try the arrApply package in your browser

Any scripts or data that you put into this service are public.

arrApply documentation built on May 29, 2017, 5:59 p.m.