trim_rows_cols: Trim rows and/or columns from a matrix

Description

By default, the matsbyname package expands matrices with 0 rows or columns prior to matrix operations to ensure that rows and columns match. There are times when trimming rows or columns is preferred over the default behavior. This function trims rows or columns in a to match the rows or columns of mat. The return value will have rows or columns of a removed if they do not appear in mat.

Usage

trim_rows_cols(
  a = NULL,
  mat = NULL,
  margin = c(1, 2),
  warn_if_a_incomplete = TRUE,
  a_piece = "all",
  mat_piece = "all",
  notation = RCLabels::bracket_notation,
  prepositions = RCLabels::prepositions_list
)

Value

Matrix a with rows or columns trimmed to match mat.

Arguments

a: A matrix to be trimmed.
mat: The matrix to be used as the template for rows and/or columns of a.
margin: The dimension of a to be trimmed. 1 means rows; 2 means columns. Default is c(1,2).
warn_if_a_incomplete: When TRUE (the default), a warning is emitted if a is missing entries on margin that are present in mat. Default is TRUE.
a_piece: The portion of a labels to be used for comparison. Default is "all".
mat_piece: The portion of mat labels to be used for comparison. Default is "all".
notation: The notation for row and column labels. Default is RCLabels::bracket_notation.
prepositions: The strings to be treated as prepositions in row and column labels. Default is RCLabels::prepositions_list.

Details

If a is NULL, NULL is returned. If mat is NULL, a is returned unmodified. If mat has NULL dimnames, a is returned unmodified. If mat has NULL for dimnames on margin, an error is returned.

A common use case for this function is to trim a, because it has too many entries on margins compared to mat. This trimming will result in a smaller result for any mathematical operations involving a and mat. Typically, a should cover all the entries in mat on margin. Thus, by default, this function warns if a is missing entries on margin that are present in mat. To turn off this checking behavior, set warn_if_a_incomplete = FALSE.

a_piece and mat_piece control which part of row and column names are compared before trimming. The default values for a_piece and mat_piece are "all", meaning that the entire label should be matched. Other options for a_piece and mat_piece are "pref" and "suff", which will match the prefix or suffix of the labels. Alternatively, prepositions can be given such that objects of prepositions will be matched. Examples include "from" or "in". See RCLabels::get_piece() for details.

Examples

Run this code

a <- matrix(c(1, 2, 3, 
              4, 5, 6, 
              7, 8, 9), nrow = 3, ncol = 3, byrow = TRUE, 
            dimnames = list(c("r1", "r2", "r3"), c("c1", "c2", "c3"))) %>% 
 setrowtype("rowtype") %>% setcoltype("coltype")
mat <- matrix(c(1, 2, 3,
                4, 5, 6), nrow = 2, ncol = 3, byrow = TRUE, 
            dimnames = list(c("r1", "bogus"), c("c1", "bogus", "c2"))) %>% 
 setrowtype("rowtype") %>% setcoltype("coltype")
trim_rows_cols(a, mat, margin = 1)
trim_rows_cols(a, mat, margin = 2)
trim_rows_cols(a, mat)