Applies a function to the matrix with behavior determined by the active component:
activate(matrix):fnis applied to the entire matrix at once. Use functions likelog,exp,sqrt, or anonymous functions like\(x) x^2.activate(rows):fnis applied independently to each row vector and must return a vector of the same length.activate(columns):fnis applied independently to each column vector and must return a vector of the same length.
Arguments
- .data
A tidymatrix object
- fn
A function to apply. When matrix is active, receives the full matrix. When rows or columns are active, receives one row or column vector at a time. Must return values with the same dimensions.
- ...
Additional arguments passed to
fn. With rows active they may refer to columns ofcol_data; with columns active, to columns ofrow_data. Avoid argument names that partially matchfn(such asf), as R would match them tofn.
Details
Additional arguments in ... are passed on to fn. With rows
or columns active they are evaluated with the metadata of the other
dimension as a data mask, in the same way as in dplyr::mutate().
A row vector has one element per matrix column, so with rows active a
column of col_data lines up element by element with the vector that
fn receives (and likewise for columns and row_data). This
makes it possible to transform values depending on their metadata, e.g.
to reverse-score some questionnaire items (see examples). Use
.env$x to refer to a variable x in the calling
environment when a metadata column has the same name. With the matrix
active, arguments are evaluated normally.
Examples
mat <- matrix(1:12, nrow = 3, ncol = 4)
tm <- tidymatrix(mat)
# Element-wise: apply log to entire matrix
tm |>
activate(matrix) |>
transform_matrix(log)
#> # A tidymatrix: 3 x 4 matrix
#> # Active: matrix
#> #
#> # Row data: 3 rows x 1 columns
#> # Column data: 4 rows x 1 columns
#> #
#> # Matrix preview:
#> [,1] [,2] [,3] [,4]
#> [1,] 0.0000000 1.386294 1.945910 2.302585
#> [2,] 0.6931472 1.609438 2.079442 2.397895
#> [3,] 1.0986123 1.791759 2.197225 2.484907
# Row-wise: rank values within each row
tm |>
activate(rows) |>
transform_matrix(rank)
#> # A tidymatrix: 3 x 4 matrix
#> # Active: rows
#> #
#> # Row data: 3 rows x 1 columns
#> # Column data: 4 rows x 1 columns
#> #
#> # Active data (rows):
#> .row_id
#> 1 1
#> 2 2
#> 3 3
# Column-wise: min-max normalize each column to [0, 1]
tm |>
activate(columns) |>
transform_matrix(\(x) (x - min(x)) / (max(x) - min(x)))
#> # A tidymatrix: 3 x 4 matrix
#> # Active: columns
#> #
#> # Row data: 3 rows x 1 columns
#> # Column data: 4 rows x 1 columns
#> #
#> # Active data (columns):
#> .col_id
#> 1 1
#> 2 2
#> 3 3
#> 4 4
# Passing extra arguments: round to 2 decimal places
tm |>
activate(matrix) |>
transform_matrix(round, digits = 2)
#> # A tidymatrix: 3 x 4 matrix
#> # Active: matrix
#> #
#> # Row data: 3 rows x 1 columns
#> # Column data: 4 rows x 1 columns
#> #
#> # Matrix preview:
#> [,1] [,2] [,3] [,4]
#> [1,] 1 4 7 10
#> [2,] 2 5 8 11
#> [3,] 3 6 9 12
# Arguments can use the metadata of the other dimension. Reverse-score
# the questionnaire items flagged in the column metadata (1 <-> 5):
big5 <- tidymatrix(big5_responses, big5_respondents, big5_items)
big5 |>
activate(rows) |>
transform_matrix(\(x, flip) ifelse(flip, 6L - x, x), flip = reversed)
#> # A tidymatrix: 400 x 30 matrix
#> # Active: rows
#> #
#> # Row data: 400 rows x 8 columns
#> # Column data: 30 rows x 5 columns
#> #
#> # Active data (rows):
#> respondent_id age gender education occupation country life_satisfaction
#> 1 R001 52 Female Secondary Service/Manual EE 8
#> 2 R002 32 Female Master Office FI 4
#> 3 R003 66 Male Bachelor Office EE 6
#> 4 R004 42 Male Bachelor Professional EE 9
#> 5 R005 48 Female Secondary Office FI 8
#> 6 R006 62 Female Basic Service/Manual EE 4
#> completion_min
#> 1 19.8
#> 2 6.2
#> 3 6.3
#> 4 9.7
#> 5 14.2
#> 6 11.6