# R/mean2.R In HenrikBengtsson/matrixStats: Functions that Apply to Rows and Columns of Matrices (and to Vectors)

#### Documented in mean2

```#' Fast averaging over subset of vector elements
#'
#' Computes the sample mean of all or a subset of values.
#'
#' \code{mean2(x, idxs)} gives equivalent results as \code{mean(x[idxs])},
#' but is faster and more memory efficient since it avoids the actual
#' subsetting which requires copying of elements and garbage collection
#' thereof.
#'
#' If \code{x} is \code{\link[base]{numeric}} and \code{refine = TRUE}, then a
#' two-pass scan is used to calculate the average.  The first scan calculates
#' the total sum and divides by the number of (non-missing) values.  In the
#' second scan, this average is refined by adding the residuals towards the
#' first average.  The \code{\link[base]{mean}}() uses this approach.
#' \code{mean2(..., refine = FALSE)} is almost twice as fast as
#' \code{mean2(..., refine = TRUE)}.
#'
#' @inheritParams rowAlls
#'
#' @param refine If \code{\link[base:logical]{TRUE}} and \code{x} is
#' \code{\link[base]{numeric}}, then extra effort is used to calculate the
#' average with greater numerical precision, otherwise not.
#'
#' @return Returns a \code{\link[base]{numeric}} scalar.
#'
#' @example incl/mean2.R
#'
#' @author Henrik Bengtsson
#'
#' To efficiently sum over a subset, see \code{\link{sum2}}().
#' @keywords univar internal
#' @export
mean2 <- function(x, idxs = NULL, na.rm = FALSE, refine = TRUE, ...) {
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Validate arguments
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Argument 'x':
if (!is.numeric(x) && !is.logical(x)) {
stop(sprintf("Argument '%s' is not numeric or logical: %s", "x", mode(x)))
}

# Argument 'na.rm':
if (!is.logical(na.rm)) {
stop(sprintf("Argument '%s' is not logical: %s", "na.rm", mode(na.rm)))
}

# Argument 'refine':
if (!is.logical(refine)) {
stop(sprintf("Argument '%s' is not logical: %s", "refine", mode(refine)))
}

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Averaging
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
.Call(C_mean2, x, idxs, na.rm, refine)
}
```
HenrikBengtsson/matrixStats documentation built on Nov. 8, 2023, 9:39 p.m.