trim_rows_cols {matsbyname}

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
)

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.

Value

Matrix a with rows or columns trimmed to match mat.

See Also

RCLabels::get_piece(), which is used internally.

Examples

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)