R: Expanded "which"-like functionality.

mwhich {bigmemory} | R Documentation

## Expanded “which”-like functionality.

### Description

Implements `which`-like functionality for a `big.matrix`, with additional options for efficient comparisons (executed in C++); also works for regular numeric matrices without the memory overhead.

### Usage

    mwhich(x, cols, vals, comps, op = "AND")

### Arguments

`x` | a `big.matrix` (or a numeric matrix; see below).
`cols` | a vector of column indices or names.
`vals` | a list (one component for each of `cols`) of vectors of length 1 or 2; length 1 is used to test equality (or inequality), while vectors of length 2 are used for checking values in the range (`-Inf` and `Inf` are allowed). If a scalar or vector of length 2 is provided instead of a list, it will be replicated `length(cols)` times.
`comps` | a list of operators (one component for each of `cols`), including `'eq'`, `'neq'`, `'le'`, `'lt'`, `'ge'` and `'gt'`. If a single operator, it will be replicated `length(cols)` times.
`op` | the comparison operator for combining the results of the individual tests, either `'AND'` or `'OR'`.

### Details

To improve performance and avoid the creation of massive temporary vectors in R when doing comparisons, `mwhich()` efficiently executes column-by-column comparisons of values to the specified values or ranges, and then returns the row indices satisfying the comparison specified by the `op` operator. More advanced comparisons are then possible (and memory-efficient) in R by doing set operations (`union` and `intersect`, for example) on the results of multiple `mwhich()` calls.

Note that `NA` is a valid argument in conjunction with `'eq'` or `'neq'`, replacing traditional `is.na()` calls. And both `-Inf` and `Inf` can be used for one-sided inequalities.

If `mwhich()` is used with a regular numeric R `matrix`, we access the data directly and thus incur no memory overhead. Interested developers might want to look at our code for this case, which uses a handy pointer trick (accessor) in C++.

### Value

a vector of row indices satisfying the criteria.

### Author(s)

John W. Emerson <bigmemoryauthors@gmail.com>

### See Also

`big.matrix`, `which`

### Examples

    x <- as.big.matrix(matrix(1:30, 10, 3))
    options(bigmemory.allow.dimnames=TRUE)
    colnames(x) <- c("A", "B", "C")
    x[,]
    x[mwhich(x, 1:2, list(c(2,3), c(11,17)),
             list(c('ge','le'), c('gt', 'lt')), 'OR'),]

    x[mwhich(x, c("A","B"), list(c(2,3), c(11,17)),
             list(c('ge','le'), c('gt', 'lt')), 'AND'),]

    # These should produce the same answer with a regular matrix:
    y <- matrix(1:30, 10, 3)
    y[mwhich(y, 1:2, list(c(2,3), c(11,17)),
             list(c('ge','le'), c('gt', 'lt')), 'OR'),]

    y[mwhich(y, -3, list(c(2,3), c(11,17)),
             list(c('ge','le'), c('gt', 'lt')), 'AND'),]

    x[1,1] <- NA
    mwhich(x, 1:2, NA, 'eq', 'OR')
    mwhich(x, 1:2, NA, 'neq', 'AND')

    # Column 1 equal to 4 and/or column 2 less than or equal to 16:
    mwhich(x, 1:2, list(4, 16), list('eq', 'le'), 'OR')
    mwhich(x, 1:2, list(4, 16), list('eq', 'le'), 'AND')

    # Column 2 less than or equal to 15:
    mwhich(x, 2, 15, 'le')

    # No NAs in either column, and column 2 strictly less than 15:
    mwhich(x, c(1:2,2), list(NA, NA, 15), list('neq', 'neq', 'lt'), 'AND')

    x <- big.matrix(4, 2, init=1, type="double")
    x[1,1] <- Inf
    mwhich(x, 1, Inf, 'eq')
    mwhich(x, 1, 1, 'gt')
    mwhich(x, 1, 1, 'le')

[Package bigmemory version 4.5.36 Index]