slam (version 0.1-54)

rollup: Rollup Sparse Arrays

Description

Rollup (aggregate) sparse arrays along arbitrary dimensions.

Usage

rollup(x, MARGIN, INDEX, FUN, ...)
# S3 method for simple_triplet_matrix
rollup(x, MARGIN, INDEX = NULL, FUN = sum, ...,
       REDUCE = FALSE)
# S3 method for simple_sparse_array
rollup(x, MARGIN, INDEX = NULL, FUN = sum, ..., 
       DROP = FALSE, EXPAND = c("none", "sparse", "dense", "all"), 
       MODE = "double")
# S3 method for matrix
rollup(x, MARGIN, INDEX = NULL, FUN = sum, ...,
       DROP = FALSE, MODE = "double")
# S3 method for array
rollup(x, MARGIN, INDEX = NULL, FUN = sum, ..., 
       DROP = FALSE, MODE = "double")

Value

An object of the same class as x where for class simple_triplet_matrix the values are always of type double

if FUN = sum (default).

The dimnames corresponding to MARGIN are based on (the components of) INDEX.

Arguments

x

a sparse (or dense) array, typically of numeric or logical values.

MARGIN

a vector giving the subscripts (names) of the dimensions to be rolled up.

INDEX

a corresponding (list of) factor (components) in the sense that as.factor defines the grouping(s). If NULL collapses the corresponding dimension(s) (default).

FUN

the name of the function to be applied.

REDUCE

option to remove zeros from the result.

DROP

option to delete the dimensions of the result which have only one level.

EXPAND

the cell expansion method to use (see Details).

MODE

the type to use for the values if the result is empty.

...

optional arguments to FUN.

Author

Christian Buchta

Details

Provides aggregation of sparse and dense arrays, in particular fast summation over the rows or columns of sparse matrices in simple_triplet-form.

If (a component of) INDEX contains NA values the corresponding parts of x are omitted.

For simple_sparse_array the following cell expansion methods are provided:

none:

The non-zero entries of a cell, if any, are supplied to FUN as a vector.

sparse:

The number of zero entries of a cell is supplied in addition to above, as a second argument.

dense:

Cells with non-zero entries are expanded to a dense array and supplied to FUN.

all:

All cells are expanded to a dense array and supplied to FUN.

Note that the memory and time consumption increases with the level of expansion.

Note that the default method tries to coerce x to array.

See Also

simple_triplet_matrix and simple_sparse_array for sparse arrays.

apply for dense arrays.

Examples

##
x <- matrix(c(1, 0, 0, 2, 1, NA), nrow = 2, 
	    dimnames = list(A = 1:2, B = 1:3))
x
apply(x, 1L, sum, na.rm = TRUE)
##
rollup(x, 2L, na.rm = TRUE)
##
rollup(x, 2L, c(1,2,1), na.rm = TRUE)
## omit
rollup(x, 2L, c(1,NA,1), na.rm = TRUE)
## expand
a <- as.simple_sparse_array(x)
a
r <- rollup(a, 1L, FUN = mean, na.rm = TRUE, EXPAND = "dense")
as.array(r)
## 
r <- rollup(a, 1L, FUN = function(x, nz) 
	length(x) / (length(x) + nz), 
    EXPAND = "sparse"
)
as.array(r)