matrixStats (version 0.12.2)

sumOver: Fast sum over subset of vector elements

Description

Computes the sum of all or a subset of values.

Usage

sumOver(x, idxs=NULL, na.rm=FALSE, mode=typeof(x), ...)

Arguments

x

A numeric vector of length N.

idxs

A numeric index vector in [1,N] of elements to sum over. If NULL, all elements are considered.

na.rm

If TRUE, missing values are skipped, otherwise not.

mode

A character string specifying the data type of the return value. Default is to use the same mode as argument x.

...

Not used.

Value

• Returns a scalar of the data type specified by argument mode. If mode="integer", then integer overflow occurs if the sum is outside the range of defined integer values.

Details

sumOver(x, idxs) gives equivalent results as sum(x[idxs]), but is faster and more memory efficient since it avoids the actual subsetting which requires copying of elements and garbage collection thereof.

Furthermore, sumOver(x, mode="double") is equivalent to sum(as.numeric(x)), but is much more memory efficient when x is an integer vector.

See Also

sum(). To efficiently average over a subset, see meanOver().

Examples

x <- 1:10
n <- length(x)

idxs <- seq(from=1, to=n, by=2)
s1 <- sum(x[idxs])                        # 25
s2 <- sumOver(x, idxs=idxs)               # 25
stopifnot(identical(s1, s2))

idxs <- seq(from=n, to=1, by=-2)
s1 <- sum(x[idxs])                        # 25
s2 <- sumOver(x, idxs=idxs)               # 25
stopifnot(identical(s1, s2))

s1 <- sum(x)                              # 55
s2 <- sumOver(x)                          # 55
stopifnot(identical(s1, s2))


# Total gives integer overflow
x <- c(.Machine$integer.max, 1L, -.Machine$integer.max)
s1 <- sum(x[1:2])                         # NA_integer_
s2 <- sumOver(x[1:2])                     # NA_integer_
stopifnot(identical(s1, s2))

# Total gives integer overflow (coerce to numeric)
s1 <- sum(as.numeric(x[1:2]))             # 2147483648
s2 <- sumOver(as.numeric(x[1:2]))         # 2147483648
s3 <- sumOver(x[1:2], mode="double")      # 2147483648
stopifnot(identical(s1, s2))
stopifnot(identical(s1, s3))

# Cumulative sum would give integer overflow but not the total
s1 <- sum(x)                              # 1L
s2 <- sumOver(x)                          # 1L
stopifnot(identical(s1, s2))