reallocate_byname: Reallocate values from one row or column to others

In matsbyname: An Implementation of Matrix Mathematics that Respects Row and Column Names

Reallocate values from one row or column to others

Description

There are situations where it is helpful to reallocate values from one row or column to another, in proportion to remaining values in corresponding columns or rows. This function performs the reallocation operation. See examples.

Usage

reallocate_byname(
  a,
  rownames = NULL,
  colnames = NULL,
  margin,
  .zero_behaviour = c("error", "warning", "zeroes", "allocate equally"),
  piece_rownames = "all",
  pattern_type_rownames = "exact",
  prepositions_rownames = RCLabels::prepositions_list,
  notation_rownames = RCLabels::notations_list,
  inf_notation_rownames = TRUE,
  choose_most_specific_rownames = FALSE,
  piece_colnames = "all",
  pattern_type_colnames = "exact",
  prepositions_colnames = RCLabels::prepositions_list,
  notation_colnames = RCLabels::notations_list,
  inf_notation_colnames = TRUE,
  choose_most_specific_colnames = FALSE
)

Arguments

a	A matrix or a list of matrices.
rownames	The row names to reallocate. NULL (the default) means include all rows.
colnames	The column names to reallocate. NULL (the default) means include all rows.
margin	An integer vector of length 1 or a vector of integers where each entry has length 1. The margin of the matrix over which the reallocation should occur. The only valid values are 1 (reallocate to other rows) or 2 (reallocate to other columns). To reallocate both rows and columns, call the function twice.
.zero_behaviour	Tells how to proceed when remaining (i.e., unallocated) rows or columns are all zero. Default is "error", which throws an error. See details for other options. If a is a list, applies to all items in the list.
piece_rownames, piece_colnames	The piece of row or column names to be assessed. Default is "all", indicating that the entire label will be assessed. If a is a list, applies to all items in the list.
pattern_type_rownames, pattern_type_colnames	The pattern type desired for row and column names. Default is "exact". Other options are "leading", "trailing", "anywhere", and "literal". See RCLabels::make_or_pattern() for details. If a is a list, applies to all items in the list.
prepositions_rownames, prepositions_colnames	Prepositions used by select_rowcol_piece_byname() for row and column name matching. Default is RCLabels::prepositions_list. If a is a list, applies to all items in the list.
notation_rownames, notation_colnames	The row or column notation used by select_rowcol_piece_byname() for row and column name matching. Default is RCLabels::notations_list. If a is a list, applies to all items in the list.
inf_notation_rownames, inf_notation_colnames	A boolean used by select_rowcol_piece_byname() that tells whether to infer notation for rows and columns. Default is TRUE. See RCLabels::infer_notation() for details. If a is a list, applies to all items in the list.
choose_most_specific_rownames, choose_most_specific_colnames	A boolean used by select_rowcol_piece_byname() that tells whether to choose the most specific notation from notation when inferring notation. Default is FALSE so that a less specific notation can be inferred. In combination with notations_lists, the default value of FALSE means that RCLabels::bracket_notation will be selected instead of anything more specific, such as RCLabels::from_notation. If a is a list, applies to all items in the list.

Details

This function will provide answers, but it is unlikely that the answers will be meaningful when the remaining data (the rows or columns not being reallocated) contain negative numbers.

The value of margin affects the interpretation of rownames and colnames. If margin = 1, rownames identifies the rows to be reallocated to other rows. colnames identifies the columns to be reallocated, where NULL (the default) means that all columns are reallocated. If margin = 2, colnames identifies the columns to be reallocated to other columns. rownames identifies the rows to be reallocated, where NULL (the default) means that all rows are reallocated.

When the remaining rows or columns not being reallocated contain exclusively zeroes, the result is determined by .zero_behaviour. Options are one of:

• "error" (the default) to throw an error.

• "warning" to issue a warning but continue execution. Be careful with this option!

• "zeroes" to return zeroes in the row or column with zeroes. Note that "zeroes" and "warning" return the same value. "zeroes" does so without a warning.

• "allocate equally" to equally allocate across remaining rows or columns.

Value

A modified version of a with rownames or colnames redistributed.

Examples

m <- 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")))
m
# Move row 3 into the other rows (r1 and r2) proportionally
reallocate_byname(m, rownames = "r3", margin = 1)
# Move column 2 into the other columns (c1 and c3) proportionally
reallocate_byname(m, colnames = "c2", margin = 2)
# Demonstrate different options for reallocating when zeroes remain.
m2 <- matrix(c(1, 2,  0,
               4, 5,  0,
               7, 8, 10), 
             nrow = 3, ncol = 3, byrow = TRUE, 
             dimnames = list(c("r1", "r2", "r3"), 
             c("c1", "c2", "c3")))
m2
reallocate_byname(m2, rownames = "r3", margin = 1, 
                  .zero_behaviour = "zeroes")
reallocate_byname(m2, rownames = "r3", margin = 1, 
                  .zero_behaviour = "allocate equally")
## Not run: 
# "error" will cause an error to be emitted.
reallocate_byname(m2, rownames = "r3", margin = 1, 
                  .zero_behaviour = "error")
# "warning" will cause a warning to be emitted
# and will return a result that is the same as "zeroes".
reallocate_byname(m2, rownames = "r3", margin = 1, 
                  .zero_behaviour = "warning")

## End(Not run)

matsbyname documentation built on June 8, 2025, 10:08 a.m.