matsbyname (version 0.6.11)

aggregate_byname: Aggregate rows and columns in a matrix

Description

Rows (margin = 1), columns (margin = 2), or both (margin = c(1, 2), the default) are aggregated according to aggregation_map.

Usage

aggregate_byname(
  a,
  aggregation_map = NULL,
  margin = c(1, 2),
  pattern_type = "exact"
)

Value

A version of a with aggregated rows and/or columns

Arguments

a

A matrix or list of matrices whose rows or columns are to be aggregated.

aggregation_map

A named list of rows or columns to be aggregated (or NULL). See details.

margin

1, 2, or c(1, 2) for row aggregation, column aggregation, or both. As a string, margin can be a row or column type. Default is c(1, 2).

pattern_type

See RCLabels::make_or_pattern(). Default is "exact".

Details

When aggregation_map is NULL (the default), rows (or columns or both) of same name are aggregated together.

If aggregation_map is not NULL, it must be a named list. The name of each aggregation_map item is the name of a row or column in output that will contain the specified aggregation. The value of each item in aggregation_map must be a vector of names of rows or columns in a. The names in the value are aggregated and inserted into the output with the name of the value. For example aggregation_map = list(new_row = c("r1", "r2")) will aggregate rows "r1" and "r2", delete rows "r1" and "r2", and insert a new row whose name is "new_row" and whose value is the sum of rows "r1" and "r2'.

The values in the aggregation_map are interpreted as regular expressions, and they are escaped using Hmisc::escapeRegex() prior to use.

margin can be a string, in which case it is interpreted as a row or column type. If a string margin does not match a row or column type, a is returned unmodified.

Note that aggregation on one margin only will sort only the aggregated margin, because the other margin is not guaranteed to have unique names.

Examples

library(dplyr)
library(tibble)
m <- matrix(1:9, byrow = TRUE, nrow = 3, 
            dimnames = list(c("r2", "r1", "r1"), c("c2", "c1", "c1"))) %>% 
  setrowtype("rows") %>% setcoltype("cols")
# Aggregate all rows by establishing an aggregation map (`am`)
am <- list(new_row = c("r1", "r2"))
aggregate_byname(m, aggregation_map = am, margin = 1)
# aggregate_byname() also works with lists and in data frames
m1 <- matrix(42, nrow = 1, dimnames = list(c("r1"), c("c1")))
m2 <- matrix(1:4, byrow = TRUE, nrow = 2, 
             dimnames = list(c("a", "a"), c("a", "a")))
m3 <- matrix(1:9, byrow = TRUE, nrow = 3, 
             dimnames = list(c("r2", "r1", "r1"), c("c2", "c1", "c1")))
DF <- tibble(m = list(m1, m1, m1, m2, m2, m2, m3, m3, m3), 
             margin = list(1, 2, c(1,2), 1, 2, c(1, 2), 1, 2, c(1, 2))) %>% 
  mutate(
    aggregated = aggregate_byname(m, margin = margin), 
  )
m1
DF$aggregated[[1]] # by rows
DF$aggregated[[2]] # by cols
DF$aggregated[[3]] # by rows and cols
m2
DF$aggregated[[4]] # by rows
DF$aggregated[[5]] # by cols
DF$aggregated[[6]] # by rows and cols
m3
DF$aggregated[[7]] # by rows
DF$aggregated[[8]] # by cols
DF$aggregated[[9]] # by rows and cols