rollup {slam}

Rollup Sparse Arrays

Description

Rollup (aggregate) sparse arrays along arbitrary dimensions.

Usage

rollup(x, MARGIN, INDEX, FUN, ...)

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

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.

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.

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.

Note

Currently most of the code is written in R and, therefore, the memory and time it consumes is not optimal.

Author(s)

Christian Buchta

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)