R: Rollup Sparse Arrays

rollup {slam} | R Documentation

## 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)

[Package slam version 0.1-40 Index]