R: Fast Row/Column Arithmetic for Matrix-Like Objects

arithmetic {collapse} | R Documentation

## Fast Row/Column Arithmetic for Matrix-Like Objects

### Description

Fast operators to perform row- or column-wise replacing and sweeping operations of vectors on matrices, data frames, lists.

### Usage

    ## Perform the operation with v and each row of X

    X %rr% v    # Replace rows of X with v
    X %r+% v    # Add v to each row of X
    X %r-% v    # Subtract v from each row of X
    X %r*% v    # Multiply each row of X with v
    X %r/% v    # Divide each row of X by v

    ## Perform a column-wise operation between V and X

    X %cr% V    # Replace columns of X with V
    X %c+% V    # Add V to columns of X
    X %c-% V    # Subtract V from columns of X
    X %c*% V    # Multiply columns of X with V
    X %c/% V    # Divide columns of X by V

### Arguments

`X` | a vector, matrix, data frame or list like object (with rows (r) columns (c) matching `v` / `V`).
`v` | for row operations: an atomic vector of matching `NCOL(X)`. If `X` is a data frame, `v` can also be a list of scalar atomic elements. It is also possible to sweep lists of vectors `v` out of lists of matrices or data frames `X`.
`V` | for column operations: a suitable scalar, vector, or matrix / data frame matching `NROW(X)`. `X` can also be a list of vectors / matrices in which case `V` can be a scalar / vector / matrix or matching list of scalars / vectors / matrices.

### Details

With a matrix or data frame `X`, the default behavior of R when calling `X op v` (such as multiplication `X * v`) is to perform the operation of `v` with each column of `X`. The equivalent operation is performed by `X %cop% V`, with the difference that it computes significantly faster if `X`/`V` is a data frame / list. A more complex but frequently required task is to perform an operation with `v` on each row of `X`. This is provided based on efficient C++ code by the `%rop%` set of functions, e.g. `X %r*% v` efficiently multiplies `v` to each row of `X`.

### Value

`X` where the operation with `v` / `V` was performed on each row or column. All attributes of `X` are preserved.

### Note

Computations and Output: These functions are all quite simple, they only work with `X` on the LHS i.e. `v %op% X` will likely fail. The row operations are simple wrappers around `TRA` which provides more operations including grouped replacing and sweeping (where `v` would be a matrix or data frame with less rows than `X` being mapped to the rows of `X` by grouping vectors). One consequence is that just like `TRA`, row-wise mathematical operations (+, -, *, /) always yield numeric output, even if both `X` and `v` may be integer. This is different for column- operations which depend on base R and may also preserve integer data.

Rules of Arithmetic: Since these operators are defined as simple infix functions, the normal rules of arithmetic are not respected. So `a %c+% b %c*% c` evaluates as `(a %c+% b) %c*% c`. As with all chained infix operations, they are just evaluated sequentially from left to right.

Performance Notes: The function `setop` and a related set of `%op=%` operators can be used to perform these operations by reference, and are faster if copies of the output are not required!! Furthermore, for Fast Statistical Functions, using `fmedian(X, TRA = "-")` will be a tiny bit faster than `X %r-% fmedian(X)`. Also use `fwithin(X)` for fast centering using the mean, and `fscale(X)` for fast scaling and centering or mean-preserving scaling.

### See Also

`setop`, `TRA`, `dapply`, Efficient Programming, Data Transformations, Collapse Overview

### Examples

    ## Using data frame's / lists
    v <- mtcars$cyl
    mtcars %cr% v
    mtcars %c-% v
    mtcars %r-% seq_col(mtcars)
    mtcars %r-% lapply(mtcars, quantile, 0.28)

    mtcars %c*% 5       # Significantly faster than mtcars * 5
    mtcars %c*% mtcars  # Significantly faster than mtcars * mtcars

    ## Using matrices
    X <- qM(mtcars)
    X %cr% v
    X %c-% v
    X %r-% dapply(X, quantile, 0.28)

    ## Chained Operations
    library(magrittr) # Note: Used because |> is not available on older R versions
    mtcars %>% fwithin() %r-% rnorm(11) %c*% 5 %>%
        tfm(mpg = fsum(mpg)) %>% qsu()

[Package collapse version 1.7.6 Index]