Skip to contents

Function assertRowsAndColumns()

If you want to do calculations with a set of matrices it is important that all matrices have the same dimensions and that rows and columns of the same name are found at the same row and column indices, respectively. The function assertRowsAndColumns() takes a matrix as input and returns a matrix as output. The function guarantees that the returned matrix contains rows and columns of requested names in requested orders. It does so by

  • creating rows/columns that are requested but not contained in the input matrix,
  • removing rows/columns that are contained in the input matrix but not requested,
  • moving rows/columns that are contained in the input matrix but not in the requested order.

Imagine three different matrices, each of with is created with createMatrix(), another function from this package:

(m_1 <- kwb.utils::createMatrix(c("a", "c"), c("x", "y"), value = 1))
#>   x y
#> a 1 1
#> c 1 1
(m_2 <- kwb.utils::createMatrix(c("a", "b"), c("x", "z"), value = 2))
#>   x z
#> a 2 2
#> b 2 2
(m_3 <- kwb.utils::createMatrix(c("b", "c"), c("y", "z"), value = 3))
#>   y z
#> b 3 3
#> c 3 3

Each matrix has two out of three possible rows a, b and c and has two out of three possible columns x, y and z. You can now unify the shape of all matrices by means of assertRowsAndColumns(), specifying the rows and columns to be required:

row_names <- c("a", "b", "c")
col_names <- c("x", "y", "z")

(m_1 <- kwb.utils::assertRowsAndColumns(m_1, row_names, col_names))
#>   x y z
#> a 1 1 0
#> b 0 0 0
#> c 1 1 0
(m_2 <- kwb.utils::assertRowsAndColumns(m_2, row_names, col_names))
#>   x y z
#> a 2 0 2
#> b 2 0 2
#> c 0 0 0
(m_3 <- kwb.utils::assertRowsAndColumns(m_3, row_names, col_names))
#>   x y z
#> a 0 0 0
#> b 0 3 3
#> c 0 3 3

Missing rows or columns are inserted and filled with the value that is given in the argument fill_value (defaulting to 0, as can be seen above). Now, the matrices can e.g. be summed up:

m_1 + m_2 + m_3
#>   x y z
#> a 3 1 2
#> b 2 3 5
#> c 1 4 3

Or, they can be put into a three dimensional array:

array_3d <- array(
  c(m_1, m_2, m_3), 
  dimnames = list(row_names, col_names, 1:3), 
  dim = c(3, 3, 3)
)

array_3d
#> , , 1
#> 
#>   x y z
#> a 1 1 0
#> b 0 0 0
#> c 1 1 0
#> 
#> , , 2
#> 
#>   x y z
#> a 2 0 2
#> b 2 0 2
#> c 0 0 0
#> 
#> , , 3
#> 
#>   x y z
#> a 0 0 0
#> b 0 3 3
#> c 0 3 3

Check Functions

Function checkForMissingColumns()

Function msgAvailableFields()

Function stopIfNotMatrix()

Function warnIfEmpty()

Function warningDeprecated()