R: Applies a row-by-row (column-by-column) averaging function to...

rowAvgsPerColSet {matrixStats} | R Documentation

## Applies a row-by-row (column-by-column) averaging function to equally-sized subsets of matrix columns (rows)

### Description

Applies a row-by-row (column-by-column) averaging function to equally-sized subsets of matrix columns (rows). Each subset is averaged independently of the others.

### Usage

    rowAvgsPerColSet(X, W = NULL, rows = NULL, S, FUN = rowMeans, ...,
      na.rm = NA, tFUN = FALSE)

    colAvgsPerRowSet(X, W = NULL, cols = NULL, S, FUN = colMeans, ...,
      na.rm = NA, tFUN = FALSE)

### Arguments

`X` | A `numeric` NxM `matrix`.
`W` | An optional `numeric` NxM `matrix` of weights.
`rows` | A `vector` indicating subset of rows to operate over. If `NULL`, no subsetting is done.
`S` | An `integer` KxJ `matrix` specifying the J subsets. Each column holds K column (row) indices for the corresponding subset.
`FUN` | The row-by-row (column-by-column) `function` used to average over each subset of `X`. This function must accept a `numeric` NxK (KxM) `matrix` and the `logical` argument `na.rm`, and return a `numeric` `vector` of length N (M).
`...` | Additional arguments passed to then `FUN` `function`.
`na.rm` | (logical) Argument passed to `FUN()` as `na.rm = na.rm`. If `NA` (default), then `na.rm = TRUE` is used if `X` or `S` holds missing values, otherwise `na.rm = FALSE`.
`tFUN` | If `TRUE`, the NxK (KxM) `matrix` passed to `FUN()` is transposed first.
`cols` | A `vector` indicating subset of columns to operate over. If `NULL`, no subsetting is done.

### Details

If argument `S` is a single column vector with indices `1:N`, then `rowAvgsPerColSet(X, S = S, FUN = rowMeans)` gives the same result as `rowMeans(X)`. Analogously, for `colAvgsPerRowSet()`.

### Value

Returns a `numeric` JxN (MxJ) `matrix`, where row names equal `rownames(X)` (`colnames(S)`) and column names `colnames(S)` (`colnames(X)`).

### Author(s)

Henrik Bengtsson

### Examples

    X <- matrix(rnorm(20 * 6), nrow = 20, ncol = 6)
    rownames(X) <- LETTERS[1:nrow(X)]
    colnames(X) <- letters[1:ncol(X)]
    print(X)

    # - - - - - - - - - - - - - - - - - - - - - - - - - -
    # Apply rowMeans() for 3 sets of 2 columns
    # - - - - - - - - - - - - - - - - - - - - - - - - - -
    nbr_of_sets <- 3
    S <- matrix(1:ncol(X), ncol = nbr_of_sets)
    colnames(S) <- sprintf("s%d", 1:nbr_of_sets)
    print(S)

    Z <- rowAvgsPerColSet(X, S = S)
    print(Z)

    # Validation
    Z0 <- cbind(s1 = rowMeans(X[, 1:2]),
                s2 = rowMeans(X[, 3:4]),
                s3 = rowMeans(X[, 5:6]))
    stopifnot(identical(drop(Z), Z0))

    # - - - - - - - - - - - - - - - - - - - - - - - - - -
    # Apply colMeans() for 5 sets of 4 rows
    # - - - - - - - - - - - - - - - - - - - - - - - - - -
    nbr_of_sets <- 5
    S <- matrix(1:nrow(X), ncol = nbr_of_sets)
    colnames(S) <- sprintf("s%d", 1:nbr_of_sets)
    print(S)

    Z <- colAvgsPerRowSet(X, S = S)
    print(Z)

    # Validation
    Z0 <- rbind(s1 = colMeans(X[  1:4, ]),
                s2 = colMeans(X[  5:8, ]),
                s3 = colMeans(X[ 9:12, ]),
                s4 = colMeans(X[13:16, ]),
                s5 = colMeans(X[17:20, ]))
    stopifnot(identical(drop(Z), Z0))

    # - - - - - - - - - - - - - - - - - - - - - - - - - -
    # When there is only one "complete" set
    # - - - - - - - - - - - - - - - - - - - - - - - - - -
    nbr_of_sets <- 1
    S <- matrix(1:ncol(X), ncol = nbr_of_sets)
    colnames(S) <- sprintf("s%d", 1:nbr_of_sets)
    print(S)

    Z <- rowAvgsPerColSet(X, S = S, FUN = rowMeans)
    print(Z)

    Z0 <- rowMeans(X)
    stopifnot(identical(drop(Z), Z0))

    nbr_of_sets <- 1
    S <- matrix(1:nrow(X), ncol = nbr_of_sets)
    colnames(S) <- sprintf("s%d", 1:nbr_of_sets)
    print(S)

    Z <- colAvgsPerRowSet(X, S = S, FUN = colMeans)
    print(Z)

    Z0 <- colMeans(X)
    stopifnot(identical(drop(Z), Z0))

[Package matrixStats version 0.61.0 Index]