Movatterモバイル変換

Replace Parts of a matrixset

Description

Replace whole or parts of some - or all - matrices of amatrixset.

Usage

## S3 replacement method for class 'matrixset'x[i = NULL, j = NULL, matrix = NULL] <- value

Arguments

Numeric values are coerced to integer as by [as.integer()] (and hencetruncated towards zero).Character vectors will be matched to the dimnames of the object.Can also be logical vectors, indicating elements/slices to replace Suchvectors are **NOT** recycled, which is an important difference with usualmatrix replacement. It means that the logical vector must match theobject dimension in length.Can also be negative integers, indicating elements/slices to leave out ofthe replacement.When indexing, a single argument `i` can be a matrix with two columns.This is treated as if the first column was the `i` index and the secondcolumn the `j` index.

Details

Ifmatrix is left unspecified (or given asNULL), all matrices will bereplaced byvalue. How replacement exactly occurs depends onvalue itself.

Ifvalue is a single atomicvector (this excludes lists) ormatrix,relevant subscripts of all requested matrices will be replaced by the samevalue. This is conditional to the dimensions being compatible.

Alternatively,value can be a list of atomic vectors/matrices. Ifvaluehas a single element, the same rules as above apply. Otherwise, the lengthofvalue must match the number of matrices for which subscripts have to bereplaced.

If the list elements are named, the names are matched to the names of thematrices that need replacement - in which casevalue needs not to be thesame length.

A final possibility forvalue is for it to beNULL. In this case, targetmatrices are turned toNULL.

Value

Amatrixset, with proper elements replaced.

vectorvalue

Contrarily tomatrix replacement, when submitting an atomicvectorvalue, dimensions must match exactly.

ReplacingNULL matrices

Replacing subscripts ofNULL matrices is not possible, unlessvalue isitselfNULL, or a matrix the same dimensions (number of rows and columns)asx. Ifx has dimnames,value must have the same dimnames.

Examples

# an hypothetical example of students that failed 3 courses and their results# after remedial class# you can replace a line for all matrices at once. In the example, the "wrong"# tag refers to the fact that the 'failure' results do not make sense after# replacementstudent_results_wrong <- student_resultsstudent_results_wrong["student 2",,] <- c(0.81, 0.88, 0.71) # obviously, integer index works too# note how all matrices had the same replacementstudent_results_wrong# this already makes more sense in the context of the examplestudent_results[2,,] <- list(c(0,0.45,0.1), c(0.81, 0.88, 0.71))student_results# or even these two equivalent commandsstudent_results["student 2",,"remedial"] <- c(0.77, 0.83, 0.75)student_results[2,,2] <- matrix(c(0.77, 0.83, 0.75), 1, 3)

Add matrices to thematrixset object

Description

Matrices to add must be of the same dimension and dimnames as.ms.

Either a named list of matrices can be supplied, or matrices can be specifiedseparaely.

Usage

add_matrix(.ms, ...)

Arguments

Value

Amatrixset with updated matrices.

Examples

m1 <- matrix(1:60, 20, 3)dimnames(m1) <- dimnames(student_results)m2 <- matrix(101:160, 20, 3)dimnames(m2) <- dimnames(student_results)ms <- add_matrix(student_results, m1=m1, m2=m2)ms2 <- add_matrix(student_results, list(m1=m1, m2=m2))

Create/modify/delete annotations of amatrixset object

Description

An annotation is a trait that is stored in the meta (row or column) data frameof the.ms object.

Creating an annotation is done as when applying amutate() on a data frame.Thus, annotations can be created from already existing annotations.

The usage is the same as fordplyr::mutate(), so see this function forinstructions on how to create/modify or delete traits.

The only difference is that the tag is a special annotation that can't bedeleted or modify (with one exception in case of modification). The tag isthe column name of the meta data frame that holds the row or column names.The tag identity of the' object can be obtained viarow_tag() orcolumn_tag(). To modify a tag, see⁠rownames<-()⁠ or⁠colnames<-()⁠.

Usage

annotate_row(.ms, ...)annotate_column(.ms, ...)

Arguments

Value

Amatrixset with updated meta info.

See Also

annotate_row_from_apply()/annotate_column_from_apply(), a version thatallows access to thematrixset matrices.

Examples

# You can create annotation from scrath or using already existing annotationms <- annotate_row(student_results,                   dummy = 1,                   passed = ifelse(previous_year_score >= 0.6, TRUE, FALSE))# There is a direct access to matrix content with annotate_row_from_apply(),# but here is an example on how it can be done with annotate_row()ms <- annotate_row(student_results,                   mn_fail = apply_matrix_dfl(student_results, mn=~ rowMeans(.m1),                                              .matrix_wise = FALSE)$mn)

Apply functions to a single matrix of a matrixset and store results as annotation

Description

This is in essenceapply_row_dfw()/apply_column_dfw(), but with theresults saved as new annotations. As such, the usage is almost identical tothese functions, except that only a single matrix can be used, and must bespecified (matrix specification differs also slightly).

Usage

annotate_row_from_apply(  .ms,  .matrix,  ...,  names_prefix = "",  names_sep = "_",  names_glue = NULL,  names_sort = FALSE,  names_vary = "fastest",  names_expand = FALSE)annotate_column_from_apply(  .ms,  .matrix,  ...,  names_prefix = "",  names_sep = "_",  names_glue = NULL,  names_sort = FALSE,  names_vary = "fastest",  names_expand = FALSE)

Arguments

Details

A conscious choice was made to provide this functionality only for⁠apply_*_dfw()⁠, as this is the only version for which the output dimensionis guaranteed to respect thematrixset paradigm.

On that note, see the section 'Groupedmatrixset'.

Value

Amatrixset with updated meta info.

Groupedmatrixset

In the context of grouping, the⁠apply_*_dfw()⁠ functions stack the resultsfor each group value.

In the case of⁠annotate_*_from_matrix()⁠, atidyr::pivot_wider() isfurther applied to ensure compatibility of the dimension.

Thepivot_wider() argumentsnames_prefix,names_sep,names_glue,names_sort,names_vary andnames_expand can help you control the finalannotation trait names.

See Also

annotate_row()/annotate_column().

Examples

# This is the same example as in annotate_row(), but with the "proper" way# of doing itms <- annotate_row_from_apply(student_results, "failure", mn = mean)

Re-order rows or columns of amatrixset

Description

Orders the rows (arrange_row()) or columns (arrange_column()) byannotation values.

The mechanic is based on sorting the annotation data frame viadplyr'sdplyr::arrange().

This means, for instance, that grouping is ignored by default. You musteither specify the grouping annotation in the sorting annotation, or use.by_group = TRUE.

The handling of locales and handling of missing values is also governed bydplyr'sarrange().

Usage

arrange_row(.ms, ..., .by_group = FALSE)arrange_column(.ms, ..., .by_group = FALSE)

Arguments

Value

Amatrixset with re-ordered rows or columns, including updated row orcolumn meta info.

Examples

ms1 <- remove_row_annotation(student_results, class, teacher)# this would not work# remove_row_annotation(row_group_by(student_results, class), class)

Coerce object intomatrixset

Description

Turns object into amatrixset. See specific methods for more details

Usage

as_matrixset(  x,  expand = NULL,  row_info = NULL,  column_info = NULL,  row_key = "rowname",  column_key = "colname",  row_tag = ".rowname",  column_tag = ".colname")

Arguments

Value

Returns amatrixset - seematrixset().

Methods

• matrix

  Thematrix method is very similar to calling thematrixsetconstruction function, with some key differences:

  • A matrix name will be provided automatically byas_matrixset. Thename is "..1".

  • Because only matrix is provided, theexpand argument is not available

• list

  Thelist method is nearly identical to calling thematrixsetconstruction function. It only differs in that unnamedlist elementwill be padded with a name. The new padded names are the element index,prefixed by "..". Already existing names will be made unique as well. Ifname modification needs to be performed, a warning will be issued.

Examples

# We're showing how 'as_matrixset' can differ. But first, show how they can# yield the same result. Note that the list is namedlst <- list(a = matrix(1:6, 2, 3), b = matrix(101:106, 2, 3))identical(matrixset(lst), as_matrixset(lst))# Now it will differ: the list is unnamed. In fact, 'matrixset' will faillst <- list(matrix(1:6, 2, 3), matrix(101:106, 2, 3))is(try(matrixset(lst), silent = TRUE), "try-error")as_matrixset(lst)# You need to name the matrix to use 'matrixset'. A name is provided for you# with 'as_matrixset'. But you can't control what it is.as_matrixset(matrix(1:6, 2, 3))

Default value for .drop argument of function column_group_by()

Description

Default value for.drop argument of functioncolumn_group_by()

Usage

column_group_by_drop_default(.ms)

Arguments

Value

ReturnsTRUE for column-ungroupedmatrixsets. For column-grouped objects,the default is alsoTRUE unless.ms has been previously grouped with.drop = FALSE.

Examples

student_results |>    row_group_by(class, .drop = FALSE) |>    row_group_by_drop_default()

Contexts dependent functions

Description

These functions are designed to work inside certainmatrixset functions, tohave access to current group/matrix/row/column. Because of that, they willnot work in a general context.

The functions within which the context functions will work areapply_matrix(),apply_row() andapply_column() - as well as their *_dfl/*dfw variant.

Note that "current" refers to the current matrix/group/row/column, asapplicable, and possibly combined.

The context functions are:

• current_n_row() andcurrent_n_column(). They each give the number of rowsand columns, respectively, of the current matrix.

  They are the context equivalent ofnrow() andncol().

• current_row_name() andcurrent_column_name(). They provide the currentrow/column name. They are the context equivalent ofrownames() andcolnames().

• current_row_info() andcurrent_column_info(). They give access to thecurrent row/column annotation data frame. The are the context equivalentofrow_info() andcolumn_info().

• row_pos() andcolumn_pos(). They give the current row/column indices.The indices are the the ones before matrix subsetting.

• row_rel_pos() andcolumn_rel_pos(). They give the row/column indicesrelative to the current matrix. They are equivalent toseq_len(current_n_row())/seq_len(current_n_column()).

Usage

current_row_info()current_column_info()current_n_row()current_n_column()current_row_name()row_pos()row_rel_pos()current_column_name()column_pos()column_rel_pos()

Value

See each individual functions for returned value when used in proper context.If used out of context, an error condition is issued.

Examples

# this will fail (as it should), because it is used out of contextis(try(current_n_row(), silent = TRUE), "try-error")# this is one way to know the number of students per class in 'student_results'student_results |>    apply_matrix_dfl(n = ~ current_n_row(), .matrix = 1)

Subset columns using annotation values

Description

Thefilter_column() function subsets the columns of all matrices of amatrixset, retaining all columns that satisfy given condition(s). Thefunctionfilter_column works likedplyr'sdplyr::filter().

Usage

filter_column(.ms, ..., .preserve = FALSE)

Arguments

Details

The conditions are given as expressions in..., which are applied tocolumns of the annotation data frame (column_info) to determine whichcolumns should be retained.

It can be applied to both grouped and ungroupedmatrixset (seecolumn_group_by()), and section ‘Grouped matrixsets’.

Value

Amatrixset, with possibly a subset of the columns of the original object.Groups will be updated if.preserve isTRUE.

Grouped matrixsets

Row grouping (row_group_by()) has no impact on column filtering.

The impact of column grouping (column_group_by()) on column filteringdepends on the conditions. Often, column grouping will not have any impact,but as soon as an aggregating, lagging or ranking function is involved, thenthe results will differ.

For instance, the two following are not equivalent (except by purecoincidence).

student_results %>% filter_column(school_average > mean(school_average))

And it's grouped equivalent:student_results %>% column_group_by(program) %>% filter_column(school_average > mean(school_average))

In the ungrouped version, the mean ofschool_average is taken globallyandfilter_column keeps columns withschool_average greater than thisglobal average. In the grouped version, the average is calculated within eachclass and the kept columns are the ones withschool_average greaterthan the within-class average.

Examples

# Filtering using one conditionfilter_column(student_results, program == "Applied Science")# Filetring using multiple conditions. These are equivalentfilter_column(student_results, program == "Applied Science" & school_average > 0.8)filter_column(student_results, program == "Applied Science", school_average > 0.8)# The potential difference between grouped and non-grouped.filter_column(student_results, school_average > mean(school_average))student_results |>  column_group_by(program) |>  filter_column(school_average > mean(school_average))

Subset rows using annotation values

Description

Thefilter_row() function subsets the rows of all matrices of amatrixset, retaining all rows that satisfy given condition(s). The functionfilter_row works likedplyr'sdplyr::filter().

Usage

filter_row(.ms, ..., .preserve = FALSE)

Arguments

Details

The conditions are given as expressions in..., which are applied tocolumns of the annotation data frame (row_info) to determine which rowsshould be retained.

It can be applied to both grouped and ungroupedmatrixset (seerow_group_by()), and section ‘Grouped matrixsets’.

Value

Amatrixset, with possibly a subset of the rows of the original object.Groups will be updated if.preserve isTRUE.

Grouped matrixsets

Column grouping (column_group_by()) has no impact on row filtering.

The impact of row grouping (row_group_by()) on row filtering depends onthe conditions. Often, row grouping will not have any impact, but as soon asan aggregating, lagging or ranking function is involved, then the resultswill differ.

For instance, the two following are not equivalent (except by purecoincidence).

student_results %>% filter_row(previous_year_score > mean(previous_year_score))

And it's grouped equivalent:student_results %>% row_group_by(class) %>% filter_row(previous_year_score > mean(previous_year_score))

In the ungrouped version, the mean ofprevious_year_score is taken globallyandfilter_row keeps rows withprevious_year_score greater than thisglobal average. In the grouped version, the average is calculated within eachclass and the kept rows are the ones withprevious_year_score greaterthan the within-class average.

Examples

# Filtering using one conditionfilter_row(student_results, class == "classA")# Filetring using multiple conditions. These are equivalentfilter_row(student_results, class == "classA" & previous_year_score > 0.75)filter_row(student_results, class == "classA", previous_year_score > 0.75)# The potential difference between grouped and non-grouped.filter_row(student_results, previous_year_score > mean(previous_year_score))student_results |>  row_group_by(teacher) |>  filter_row(previous_year_score > mean(previous_year_score))

Group rows/columns of a matrixset by one or more variables

Description

Applyingrow_group_by() orcolumn_group_by() to amatrixset objectregisters this object as one where certain operations are performed per(row or column) group.

To (partly) remove grouping, userow_ungroup() orcolumn_ungroup().

These functions are thematrixset equivalent ofdplyr'sdplyr::group_by() anddplyr::ungroup()

Usage

row_group_by(.ms, ..., .add = FALSE, .drop = row_group_by_drop_default(.ms))column_group_by(  .ms,  ...,  .add = FALSE,  .drop = column_group_by_drop_default(.ms))row_ungroup(.ms, ...)column_ungroup(.ms, ...)

Arguments

Value

A groupedmatrixset with classrow_grouped_ms, unless.ms was alreadycolumn-grouped viacolumn_group_by(), in which case adual_grouped_msmatrixset is returned.

If the combination of... and.add yields an empty set of groupingcolumns, a regularmatrixsetor acol_grouped_ms, as appropriate, will bereturned.

Examples

by_class <- row_group_by(student_results, class)# On it's own, a grouped `matrixset` looks like a regular `matrixset`, except# that the grouping structure is listedby_class# Grouping changes how some functions operatesfilter_row(by_class, previous_year_score > mean(previous_year_score))# You can group by expressions: you end-up grouping by the new annotation:row_group_by(student_results, sqrt_score = sqrt(previous_year_score))# By default, grouping overrides existing groupingrow_group_vars(row_group_by(by_class, teacher))# Use .add = TRUE to instead appendrow_group_vars(row_group_by(by_class, teacher, .add = TRUE))# To removing grouping, use ungrouprow_ungroup(by_class)

Add meta info from anothermatrixset or adata.frame

Description

The operation is done through a join operation between the row meta infodata.frame (join_row_info()) of.ms andy (or its row meta infodata.frame if it is amatrixset object). The functionjoin_column_info()does the equivalent operation for column meta info.

The default join operation is a left join(type == 'left'), but most of dplyr'sjoins are available ('left', 'inner', 'right', 'full', 'semi' or 'anti').

Thematrixset paradigm of unique row/column names is enforced so if a.ms data.frame row matches multiple ones iny, the default behavior isto issue a condition error.

This can be modified by setting new tag names via the argumentnames_glue.

Usage

join_row_info(  .ms,  y,  type = "left",  by = NULL,  adjust = FALSE,  names_glue = NULL,  suffix = c(".x", ".y"),  na_matches = c("na", "never"))join_column_info(  .ms,  y,  type = "left",  by = NULL,  adjust = FALSE,  names_glue = NULL,  suffix = c(".x", ".y"),  na_matches = c("na", "never"))

Arguments

Value

Amatrixset with updated row or column meta info, with all.ms traits andy traits. If some traits share the same names - and were not included inby -suffixes will be appended to these names.

If adjustment was allowed, the dimensions of the newmatrixset may differfrom the original one.

Groups

Wheny is amatrixset, only groups from.ms are used, if any. Groupupdate is the same as indplyr.

Examples

ms1 <- remove_row_annotation(student_results, class, teacher)ms <- join_row_info(ms1, student_results)ms <- join_row_info(ms1, student_results, by = c(".rowname", "previous_year_score"))# This will throw an errorms2 <- remove_row_annotation(filter_row(student_results, class %in% c("classA", "classC")),                             class, teacher, previous_year_score)ms <- tryCatch(join_row_info(ms2, student_results, type = "full"),               error = function(e) e)is(ms, "error") # TRUEms$message# Now it works.ms <- join_row_info(ms2, student_results, type = "full", adjust = TRUE)dim(ms2)dim(ms)matrix_elm(ms, 1)# Similarly, this will fail because tag names are no longer uniquemeta <- tibble::tibble(sample = c("student 2", "student 2"),                      msr = c("height", "weight"),                      value = c(145, 32))ms <- tryCatch(join_row_info(student_results, meta, by = c(".rowname"="sample")),               error = function(e) e)is(ms, "error") # TRUEms$message# This works, by forcing the tag names to be unique. Notice that we suppress# the warning for now. We'll come back to it.suppressWarnings(   join_row_info(student_results, meta, by = c(".rowname"="sample"),                 adjust = TRUE, names_glue = TRUE))# Here's the warning: we're being told there was a change in tag names(purrr::quietly(join_row_info)(student_results, meta,                               by = c(".rowname"="sample"), adjust = TRUE,                               names_glue = TRUE))$warnings# You can have better control on how the tag change occurs, for instance by# appending the msr value to the namesuppressWarnings(   join_row_info(student_results, meta, by = c(".rowname"="sample"),                 adjust = TRUE, names_glue = "{.tag}_{msr}"))# In this specific example, the {.tag} was superfluous, since the default is# to append after the tag namesuppressWarnings(   join_row_info(student_results, meta, by = c(".rowname"="sample"),                 adjust = TRUE, names_glue = "{msr}"))# But the keyword is useful if you want to shuffle ordersuppressWarnings(   join_row_info(student_results, meta, by = c(".rowname"="sample"),                 adjust = TRUE, names_glue = "{msr}.{.tag}"))# You are warned when there is a change in traitsmeta <- tibble::tibble(sample = c("student 2", "student 2"),                       class = c("classA", "classA"),                       msr = c("height", "weight"),                       value = c(145, 32))(purrr::quietly(join_row_info)(student_results, meta,                               by = c(".rowname"="sample"), adjust = TRUE,                               names_glue = TRUE))$warnings[2]# Groups are automatically adjustedsr_gr <- row_group_by(student_results, class)gr_orig <- row_group_meta(row_group_by(student_results, class)) |> tidyr::unnest(.rows)suppressWarnings(  new_gr <- join_row_info(sr_gr, meta, by = c(".rowname" = "sample", "class"),                          adjust = TRUE, names_glue = TRUE) |>   row_group_meta() |> tidyr::unnest(.rows))list(gr_orig, new_gr)# In the example above, the join operation changed the class of 'class',# which in turn changed the grouping meta info. You are warned of both.(purrr::quietly(join_row_info)(sr_gr, meta,                               by = c(".rowname"="sample", "class"),                               adjust = TRUE,  names_glue = TRUE))$warnings# A change in trait name that was used for grouping will result in losing the# grouping. You are warning of the change in grouping structure.(purrr::quietly(join_row_info)(sr_gr, meta,                               by = c(".rowname"="sample"),                               adjust = TRUE,  names_glue = TRUE))$warnings

Apply functions to each matrix of a matrixset

Description

Theapply_matrix function applies functions to each matrix of amatrixset.Theapply_row/apply_column functions do the same but separately for eachrow/column. The functions can be applied to all matrices or only a subset.

Thedfl/dfw versions differ in their output format and when possible,always return atibble::tibble().

Empty matrices are simply left unevaluated. How that impacts the returnedresult depends on which flavor of apply_* has been used. See ‘Value’for more details.

If.matrix_wise isFALSE, the function (or expression) is multivariate inthe sense that all matrices are accessible at once, as opposed to each of themin turn.

See section "Multivariate".

Usage

apply_row(.ms, ..., .matrix = NULL, .matrix_wise = TRUE, .input_list = FALSE)apply_row_dfl(  .ms,  ...,  .matrix = NULL,  .matrix_wise = TRUE,  .input_list = FALSE,  .force_name = FALSE)apply_row_dfw(  .ms,  ...,  .matrix = NULL,  .matrix_wise = TRUE,  .input_list = FALSE,  .force_name = FALSE)apply_column(  .ms,  ...,  .matrix = NULL,  .matrix_wise = TRUE,  .input_list = FALSE)apply_column_dfl(  .ms,  ...,  .matrix = NULL,  .matrix_wise = TRUE,  .input_list = FALSE,  .force_name = FALSE)apply_column_dfw(  .ms,  ...,  .matrix = NULL,  .matrix_wise = TRUE,  .input_list = FALSE,  .force_name = FALSE)apply_matrix(  .ms,  ...,  .matrix = NULL,  .matrix_wise = TRUE,  .input_list = FALSE)apply_matrix_dfl(  .ms,  ...,  .matrix = NULL,  .matrix_wise = TRUE,  .input_list = FALSE,  .force_name = FALSE)apply_matrix_dfw(  .ms,  ...,  .matrix = NULL,  .matrix_wise = TRUE,  .input_list = FALSE,  .force_name = FALSE)

Arguments

Value

A list for every matrix in the matrixset object. Each list is itself alist, orNULL forNULL matrices. Forapply_matrix, it is a list ofthe function values. Otherwise, it is a list with one element for eachrow/column. And finally, forapply_row/apply_column, each of thesesub-list is a list, the results of each function.

When.matrix_wise == FALSE, the output format differs only in that there isno list for matrices.

If each function returns avector of the same dimension, you can use eitherthe⁠_dfl⁠ or the⁠_dfw⁠ version. What they do is to return a list oftibbles. Thedfl version will stack the function results in a long formatwhile thedfw version will put them side-by-side, in a wide format. Anempty matrix will be returned for empty input matrices.

If the functions returned vectors of more than one element, there will be acolumn to store the values and one for the function ID (dfl), or one columnper combination of function/result (dfw)

See the grouping section to learn about the result format in the groupingcontext.

Pronouns

Therlang pronouns.data and.env are available. Two scenarios forwhich they can be useful are:

• The annotation names are stored in a character variable. You can make useof the variable by using.data[[var]]. See the example for anillustration of this.

• You want to make use of a global variable that has the same name as anannotation. You can use.env[[var]] or.env$var to make sure to usethe proper variable.

The matrixset package defines its own pronouns: .m,.i and .j, whichare discussed in the function specification argument (...).

It is not necessary to import any of the pronouns (or loadrlang in thecase of.data and.env) in a interactive session.

It is useful however when writing a package to avoid the⁠R CMD check⁠ notes.As needed, you can import.data and.env (fromrlang) or any of .m,.i or .j frommatrixset.

Multivariate

The default behavior is to apply a function or expression to a singlematrix and each matrices of thematrixset object are provided sequentiallyto the function/expression.

If.matrix_wise isFALSE, all matrices are provided at once to thefunctions/expressions. They can be provided in two fashions:

• separately (default behavior). Each matrix can be referred by.m1, ...,.mn, wheren is the number of matrices. Note that this is the numberas determined by.matrix.

  Forapply_row (and dfl/dfw variants), use.i1,.i2 and so oninstead. What the functions/expressions have access to in this case isthe first row of the first matrix, the first row of the second matrixand so on. Then, continuing the loop, the second row of each matrixwill be accessible, and so on

  Similarly, use.j1 and so on for theapply_column family.

  Anonymous functions will be understood as a function with multiplearguments. In the exampleapply_row(ms, mean, .matrix_wise = FALSE),if there are 3 matrices in thems object,mean is understood asmean(.i1, .i2, .i3). Note that this would fail because of themeanfunction.

• In a list (.list_input = TRUE). The list will have an element per matrix.The list can be referred using the same pronouns (.m,.i,.j), andthe matrix, by the matrix names or position.

For the multivariate setting, empty matrices are given as is, so it isimportant that provided functions can deal with such a scenario. Analternative is to skip the empty matrices with the.matrix argument.

Grouped matrixsets

If groups have been defined, functions will be evaluated within them. Whenboth row and column grouping has been registered, functions are evaluated ateach cross-combination of row/column groups.

The output format is different when the.ms matrixset object is grouped.A list for every matrix is still returned, but each of these lists now holdsa tibble.

Each tibble has a column called.vals, where the function results arestored. This column is a list, one element per group. The group labels aregiven by the other columns of the tibble. For a given group, things are likethe ungrouped version: further sub-lists for rows/columns - if applicable -and function values.

The dfl/dfw versions are more similar in their output format to theirungrouped version. The format is almost identical, except that additionalcolumns are reported to identify the group labels.

See the examples.

Examples

# The firs example takes the whole matrix average, while the second takes# every row average(mn_mat <- apply_matrix(student_results, mean))(mn_row <- apply_row(student_results, mean))# More than one function can be provided. It's a good idea in this case to# name them(mn_col <- apply_column(student_results, avr=mean, med=median))# the dfl/dfw versions returns nice tibbles - if the functions return values# of the same length.(mn_l <- apply_column_dfl(student_results, avr=mean, med=median))(mn_w <- apply_column_dfw(student_results, avr=mean, med=median))# There is no difference between the two versions for length-1 vector results.# hese will differ, however(rg_l <- apply_column_dfl(student_results, rg=range))(rg_w <- apply_column_dfw(student_results, rg=range))# More complex examples can be used, by using pronouns and data annotation(vals <- apply_column(student_results, avr=mean, avr_trim=~mean(.j, trim=.05),                                      reg=~lm(.j ~ teacher)))# You can wrap complex function results, such as for lm, into a list, to use# the dfl/dfr version(vals_tidy <- apply_column_dfw(student_results, avr=mean, avr_trim=~mean(.j, trim=.05),                                               reg=~list(lm(.j ~ teacher))))# You can provide complex expressions by using formulas(r <- apply_column(student_results,                                  res= ~ {                                    log_score <- log(.j)                                    p <- predict(lm(log_score ~ teacher + class))                                    .j - exp(p)                                  }))# the .data pronoun can be useful to use names stored in variablesfn <- function(nm) {  if (!is.character(nm) && length(nm) != 1) stop("this example won't work")  apply_column(student_results, ~lm(.j ~ .data[[nm]]))}fn("teacher")# You can use variables that are outside the scope of the matrixset object.# You don't need to do anything special if that variable is not named as an# annotationpass_grade <- 0.5(passed <- apply_row_dfw(student_results, pass = ~ .i >= pass_grade))# use .env if shares an annotation nameprevious_year_score <- 0.5(passed <- apply_row_dfw(student_results, pass = ~ .i >= .env$previous_year_score))# Grouping structure makes looping easy. Look at the output formatcl_prof_gr <- row_group_by(student_results, class, teacher)(gr_summ <- apply_column(cl_prof_gr, avr=mean, med=median))(gr_summ_tidy <- apply_column_dfw(cl_prof_gr, avr=mean, med=median))# to showcase how we can play with format(gr_summ_tidy_long <- apply_column_dfl(cl_prof_gr, summ = ~ c(avr=mean(.j), med=median(.j))))# It is even possible to combine groupingscl_prof_program_gr <- column_group_by(cl_prof_gr, program)(mat_summ <- apply_matrix(cl_prof_program_gr, avr = mean, med = median, rg = range))# it doesn' make much sense, but this is to showcase format(summ_gr <- apply_matrix(cl_prof_program_gr, avr = mean, med = median, rg = range))(summ_gr_long <- apply_column_dfl(cl_prof_program_gr,                                 ct = ~ c(avr = mean(.j), med = median(.j)),                                 rg = range))(summ_gr_wide <- apply_column_dfw(cl_prof_program_gr,                                 ct = ~ c(avr = mean(.j), med = median(.j)),                                 rg = range))# This is an example where you may want to use the .force_name argument(apply_matrix_dfl(column_group_by(student_results, program), FC = ~ colMeans(.m)))(apply_matrix_dfl(column_group_by(student_results, program), FC = ~ colMeans(.m),                  .force_name = TRUE))

Matrix Set

Description

Creates a matrix set, possibly annotated for rows and/or columns. Theseannotations are referred as traits.

Usage

matrixset(  ...,  expand = NULL,  row_info = NULL,  column_info = NULL,  row_key = "rowname",  column_key = "colname",  row_tag = ".rowname",  column_tag = ".colname")

Arguments

Details

Amatrixset is a collection of matrices that share the same dimensions and,if applicable, dimnames. It is designed to hold different measures for thesame rows/columns. For example, each matrix could be a different time pointfor the same subjects.

Traits, which are annotations, can be provided in the form of data framesfor rows and/or columns. If traits are provided, thedata.frame mustcontain only one entry per row/column (see examples).

Row or column names are not mandatory to create a propermatrixset. Theonly way for this to work however is to leave traits (annotations) empty.If provided, each matrices must have the same dimnames as well.

If dimnames are missing, note that most of the operations for matrixsetswon't be available. For instance, operations that use traits will not work,e.g.,filter_row().

It is allowed for matrix elements of amatrixset to beNULL - seeexamples.

Value

Returns amatrixset, a collection of matrices (see ‘Details’).

Matrix Expansion

The concept of matrix expansion allows to provide input matrices that do notshare the same dimensions.

This works by taking the union of the dimnames and padding, if necessary,each matrix with a special value for the missing rows/columns.

Because the dimnames are used, they must necessarily be non-NULL in theprovided matrices.

An interesting side-effect is that one can use this option to match thedimnames and provide a common row/column order among the matrices.

For base matrices, the padding special value is, by default(expand = TRUE),NA. For the special matrices (Matrix package), thedefault value is0. For these special matrices, padding with 0 forcesconversion to sparse matrix.

The default value can be changed by providing any value (e.g,-1) toexpand, in which case the same padding value is used for all matrices.

If different padding values are needed for each matrices, a list can beprovided toexpand. If the list is unnamed, it must match the number ofinput matrices in length and the padding values are assigned to the matricesin order.

A named list can be provided as well. In that case,expand names andmatrix names are matched. All matrices must have a match in theexpand list(moreexpand values can be provided, though).

See Also

as_matrixset()

Examples

# A single NULL element will create an empty matrixset (it doesn't hold# any matrices)lst <- NULLmatrixset(lst)# This will hold to empty matriceslst <- list(a = NULL, b = NULL)matrixset(lst)# this is equivalentmatrixset(a = NULL, b = NULL)# A basic examplelst <- list(a = matrix(0, 2, 3))matrixset(lst)# equivalentmatrixset(a = matrix(0, 2, 3))# can mix with NULL toolst <- list(a = NULL, b = matrix(0, 2, 3), c = matrix(0, 2, 3))matset <- matrixset(lst)# dimnames are also considered to be traitslst <- list(a = NULL, b = matrix(0, 2, 3), c = matrix(0, 2, 3))rownames(lst$b) <- c("r1", "r2")rownames(lst$c) <- c("r1", "r2")matrixset(lst)# You don't have to annotate both rows and columns. But you need to provide# the appropriate dimnames when you provide traitslst <- list(a = matrix(0, 2, 3), b = matrix(0, 2, 3), c = NULL)rownames(lst$a) <- c("r1", "r2")rownames(lst$b) <- c("r1", "r2")colnames(lst$a) <- c("c1", "c2", "c3")colnames(lst$b) <- c("c1", "c2", "c3")ri <- data.frame(rowname = c("r1", "r2"), g = 1:2)matset <- matrixset(lst, row_info = ri)# You can provide a column name that contains the keysri <- data.frame(foo = c("r1", "r2"), g = 1:2)matset <- matrixset(lst, row_info = ri, row_key = "foo")lst <- list(a = matrix(0, 2, 3), b = matrix(0, 2, 3), c = NULL)rownames(lst$a) <- c("r1", "r2")rownames(lst$b) <- c("r1", "r2")colnames(lst$a) <- c("c1", "c2", "c3")colnames(lst$b) <- c("c1", "c2", "c3")ri <- data.frame(rowname = c("r1", "r2"), g = 1:2)ci <- data.frame(colname = c("c1", "c2", "c3"), h = 1:3)matset <- matrixset(lst, row_info = ri, column_info = ci)# This is not allowed, because the row trait data frame has more than one# entry for "r1"lst <- list(a = matrix(0, 2, 3), b = matrix(0, 2, 3), c = NULL)rownames(lst$a) <- c("r1", "r2")rownames(lst$b) <- c("r1", "r2")colnames(lst$a) <- c("c1", "c2", "c3")colnames(lst$b) <- c("c1", "c2", "c3")ri <- data.frame(rowname = c("r1", "r2", "r1"), g = 1:3)ci <- data.frame(colname = c("c1", "c2", "c3"), h = 1:3)ans <- tryCatch(matrixset(lst, row_info = ri, column_info = ci),                error = function(e) e)is(ans, "error")

Matrixset group metadata

Description

• row_group_meta() andcolumn_group_meta() returns the grouping structure,in a data frame format. Seedplyr'sdplyr::group_data(), from which thefunctions are based. ReturnsNULL for ungroupedmatrixsets.

• row_group_keys() andcolumn_group_keys() retrieve the grouping data,while the locations (row or column indices) are retrieved withrow_group_where() andcolumn_group_where().

• row_group_indices() andcolumn_group_indices() each return an integervector the same length as the number of rows or columns of.ms, andgives the group that each row or column belongs to.

• row_group_vars() andcolumn_group_vars() give names of groupingvariables as character vector;row_groups() andcolumn_groups() givethe names as a list of symbols.

Usage

row_group_meta(.ms)row_group_vars(.ms)row_group_keys(.ms)row_group_where(.ms)row_group_indices(.ms)row_groups(.ms)column_group_meta(.ms)column_group_vars(.ms)column_group_keys(.ms)column_group_where(.ms)column_group_indices(.ms)column_groups(.ms)

Arguments

Table S1 and S2 of MRMPlus Paper inmatrixset Format

Description

Table S1 and S2 of MRMPlus Paper inmatrixset Format

Usage

mrm_plus2015

Format

Amatrixset of 30 rows and 45 columnsThe object contains four matrices:

light_area

Peak area of light peptides.

heavy_area

Peak area of heavy peptides.

light_rt

Retention time of light peptides.

heavy_rt

Retention time of heavy peptides.

The column names, analytes, are a combination of peptide sequence andfragment ion. Rownames are the replicate names.

Source

Aiyetan P, Thomas SN, Zhang Z, Zhang H. MRMPlus: an open source qualitycontrol and assessment tool for SRM/MRM assay development. BMC Bioinformatics.2015 Dec 12;16:411. doi: 10.1186/s12859-015-0838-z. PMID: 26652794; PMCID: PMC4676880.

Convert matrixset to data frame

Description

Converts amatrixset to adata.frame (atibble, more specifically), ina long format.

Whenas_list isTRUE, each matrix is converted separately. Row/columnannotation is included if requested.

Usage

ms_to_df(  .ms,  add_row_info = TRUE,  add_column_info = TRUE,  as_list = FALSE,  .matrix = NULL)

Arguments

Value

A tibble, or ifas_list isTRUE, Alist of data frames, an element perconverted matrix

Examples

# includes both annotationms_to_df(student_results)# includes only row annotationms_to_df(student_results, add_column_info = FALSE)

Create/modify/delete matrices from amatrixset object

Description

Applies functions that takes matrices as input and return similar matrices.The definition of similar is that the new matrix has the same dimension anddimnames as.ms.

If the returned matrix is assigned to a new matrix, this matrix is added to thematrixset object. If it is assigned to an already existing matrix, itoverwrites the matrix of the same name.

Setting a matrix value toNULL willnot delete the matrix, but willcreate an empty slot (NULL) for the matrix.

To delete a matrix, use the functionremove_matrix(). See examples below.

Note that matrices are created sequentially and can be used by othername-value pairs. There is an example that showcases this.

Usage

mutate_matrix(.ms, ...)

Arguments

Value

Amatrixset with updated matrices.

Examples

# Notice how FC can be used as soon as createdms <- mutate_matrix(student_results,                    FC = remedial/failure,                    foo = NULL,                    logFC = log2(FC),                    FC = remove_matrix())# this is NULLmatrix_elm(ms, "foo")# running this would return an error, since FC was deleted# matrix_elm(ms, "FC")

Print a matrixset

Description

When printing amatrixset:

• The number of matrices and their dimension is shown

• Prints each matrix of the object, showing its type and dimension. Fullmatrices are shown only for those with 3 rows or less. Otherwise, onlythe first and last row is shown. The same also applies for the columns.

• An exception to the point above: if the number of matrices is greater thann_matrices, the firstn_matrices are displayed, while the others willbe named only.

• The row and column annotations (row_info/column_info) are displayed astibble objects.

Usage

## S3 method for class 'matrixset'print(x, ..., n_matrices = 2)

Arguments

Value

Invisibly, thematrixset object.

Examples

print(student_results)print(mrm_plus2015)

Matrixset properties

Description

Utility functions to extract relevant information from amatrixset object.

Usage

## S3 method for class 'matrixset'dim(x)## S3 method for class 'matrixset'dimnames(x)## S3 replacement method for class 'matrixset'dimnames(x) <- valuematrixnames(x)matrixnames(x) <- valuematrix_elm(x, matrix)matrix_elm(x, matrix) <- valuenmatrix(x)row_traits(x)column_traits(x)row_traits(x) <- valuecolumn_traits(x)column_traits(x) <- valuerow_tag(x)column_tag(x)row_info(x)row_info(x) <- valuecolumn_info(x)column_info(x) <- valueis_matrixset(x)

Arguments

Details

ìs_matrixset tests if its argument is a propermatrixset object.

dim retrieves the dimension of thematrixset matrices (which are thesame for reach). Similarly,nrow returns the number of rows for eachmatrices, andncol returns the number of columns.

dimnames retrieves the dimnames of thematrixset matrices (which are thesame for reach). Similarly,rownames (colnames) will retrieve row(column) names.

matrixnames retrieves the matrix names, orNULL if the matrices are notnamed.

nmatrix returns the number of matrices of amatrixset.

row_traits returns the object's row traits; these are the column names ofthe row annotation data frame.

column_traits returns the object's column traits; these are the columnnames of the column annotation data frame.

row_info extracts the row annotation data frame.column_info doesthe same thing for column annotation.

row_tag returns the column name ofrow_info that stores thematrixset'srow names.column_tag returns the column name ofcolumn_info that storesthematrixset's column names.

The replacement methods forrow_traits/row_info andcolumn_traits/column_infocan potentially change meta variables that were used for grouping. There isalways an attempt to keep the original groups, but they will be updated if itis possible - a message is issued when that happens - and otherwise removedaltogether, with a warning.

matrix_elm extracts a single matrix. It's a wrapper tox[,,matrix], butreturns the matrix element. The replacement methodmatrix_elm is also awrapper to⁠x[,,matrix] <-⁠.

Value

ìs_matrixset returns alogical.

dim returns a length-2 vector;nrow andncol return length-1 vector.

dimnames returns a length-2 list; one component for each dimnames (row andcolumn).rownames andcolnames each returns acharacter vector ofnames.

matrixnames acharacter vector of matrix names, orNULL.

nmatrix returns anìnteger.

row_traits andcolumn_traits returns acharacter vector.

row_tag andcolumn_tag returns acharacter vector.

row_info extracts the row annotation data frame.column_info doesthe same thing for column annotation.

Examples

is_matrixset(student_results)dim(student_results)c(nrow(student_results), ncol(student_results))dimnames(student_results)list(rownames(student_results), colnames(student_results))matrixnames(student_results)nmatrix(student_results)list(row_traits(student_results), column_traits(student_results))row_info(student_results)column_info(student_results)

Remove meta info of amatrixset

Description

Deletes row or column annotation (i.e., trait).

The tag is a special trait that can't be removed. The tag is the column nameof the meta data frame that holds the row or column names. The tag identityof the' object can be obtained viarow_tag() orcolumn_tag().

Usage

remove_row_annotation(.ms, ...)remove_column_annotation(.ms, ...)

Arguments

Value

Amatrixset with updated row or column meta info.

Groups

Removing a trait that is used for grouping is not allowed and will not work.

Examples

ms1 <- remove_row_annotation(student_results, class, teacher)# this doesn't work because "class" is used for groupingms2 <- tryCatch(remove_row_annotation(row_group_by(student_results, class), class),                error = function(e) e)is(ms2, "error") #TRUEms2$message

Remove one or more matrices of thematrixset object

Description

This is a special case of the[ method, with the benefit of being explicitabout what action is taken.

Usage

remove_matrix(.ms, matrix)

Arguments

Value

Amatrixset with updated matrices.

Usage insidemutate_matrix()

In most cases, both arguments of the function are mandatory. However, if youwant to declare that a matrix should be removed via themutate_matrix()function, theremove_matrix() must be called without arguments. There isan example that illustrates that.

Examples

ms1 <- remove_matrix(student_results, "remedial")ms2 <- remove_matrix(student_results, 2)ms3 <- mutate_matrix(student_results, remedial = remove_matrix())

Default value for .drop argument of function row_group_by()

Description

Default value for.drop argument of functionrow_group_by()

Usage

row_group_by_drop_default(.ms)

Arguments

Value

ReturnsTRUE for row-ungroupedmatrixsets. For row-grouped objects, thedefault is alsoTRUE unless.ms has been previously grouped with.drop = FALSE.

Examples

student_results |>    row_group_by(class, .drop = FALSE) |>    row_group_by_drop_default()

Fake Final Exam Results of School Students Before and After Remedial Courses

Description

Fake Final Exam Results of School Students Before and After Remedial Courses

Usage

student_results

Format

Amatrixset of 20 rows and 3 columnsThe object contains two matrices, one for the failure results (matrix namedfailure) and one for the results after remedial classes (matrix namedremedial). Each matrix has results for 20 students and 3 classes:

• Mathematics

• English

• Science

The object has been annotated both for rows (students) and columns (courses).Each students has been annotated for the following information:

class

Group, or class, in which the student was part of

teacher

Professor that gave the remedial course

previous_year_score

Score the student had in the previous level ofthe same class

Each course has been annotated for the following information:

national_average

National average of all students for the course

school_average

Average of the school's students for the course

program

Program in which the course is given

Subsetting matrixsets

Description

Extract parts of a matrixset, where indexes refers to rows and columns.

Usage

## S3 method for class 'matrixset'  x[  i = NULL,  j = NULL,  matrix = NULL,  drop = FALSE,  keep_annotation = TRUE,  warn_class_change = getOption("matrixset.warn_class_change")]## S3 method for class 'row_grouped_ms'  x[  i = NULL,  j = NULL,  matrix = NULL,  drop = FALSE,  keep_annotation = TRUE,  warn_class_change = getOption("matrixset.warn_class_change")]## S3 method for class 'col_grouped_ms'  x[  i = NULL,  j = NULL,  matrix = NULL,  drop = FALSE,  keep_annotation = TRUE,  warn_class_change = getOption("matrixset.warn_class_change")]## S3 method for class 'dual_grouped_ms'  x[  i = NULL,  j = NULL,  matrix = NULL,  drop = FALSE,  keep_annotation = TRUE,  warn_class_change = getOption("matrixset.warn_class_change")]## S3 method for class 'matrixset'x$matrix## S3 method for class 'matrixset'x[[matrix]]

Arguments

Details

Indexesi andj are given as for a regularmatrix()(note however that factors are currently not allowed for indexing).Which matrices are extracted (all or a subset) is specified via argument"matrix".

Missing values (NA) are not allowed for indexing, as it results inunknown selection. Character indexes use exact matching, not partial.

The default arguments for"drop" and"keep_annotation" arechosen so that the object resulting from the extraction is still amatrixset.

Setting"keep_annotation" toFALSE automatically results in a classchange (a list of matrix) and a warning is issued (see argumentwarn_class_change, however).

Settingdrop toTRUE may also result to a change of class,depending on the provided indices (the same way matrix may result to a vectorwhendrop isTRUE).

The subsetting operator[[ is a convenient wrapper for⁠[(,,matrix)⁠.

There is no$ subsetting operator for thematrixset object.

Value

The resulting object type depends on the subsetting options. By default, amatrixset object will be returned. This object will have the followingproperties:

• Rows and/or columns are a subset of the input (based on what has beensubsetted), but appear in the same order.

• Annotations, or traits, are subsetted appropriately.

• The number of groups may be reduced.

• Currently, attributes arenot preserved.

Ifkeep_annotation isFALSE, the resulting object will be a list.Typically, it will be a list ofmatrix, but ifdrop isTRUE, somelist elements could be vectors.

Grouped matrixset

When subsetting a groupedmatrixset (by rows and/or columns), when theresulting object is still amatrixset, the grouping structure will beupdated based on the resulting data.

Examples

lst <- list(a = matrix(1:6, 2, 3), b = matrix(101:106, 2, 3), c = NULL)rownames(lst$a) <- rownames(lst$b) <- c("r1", "r2")colnames(lst$a) <- colnames(lst$b) <- c("c1", "c2", "c3")ri <- data.frame(rowname = c("r1", "r2"), g = 1:2)ci <- data.frame(colname = c("c1", "c2", "c3"), h = 1:3)matset <- matrixset(lst, row_info = ri, column_info = ci, row_tag = "foo", column_tag = "bar")# this doesn't subset anything, just returns matset againmatset[]# this extracts the first row of every matrix. Note how each matrices is# still a matrix, so you still end up with a matrixset object. Note also# that you need placeholder for j and matrix index, even when not providedmatset[1, , ]# similar ideamatset[,2, ]matset[1,2,]# it obviously works with vector indexesmatset[1:2, c(1,3),]# you can extract the matrices this - even without the 'annoying' warningmatset[, , , keep_annotation = FALSE]matset[, , , keep_annotation = FALSE, warn_class_change = FALSE]# extracts subsetted matrices (no annotations)matset[1, , , keep_annotation = FALSE, warn_class_change = FALSE]# a bit more in line with how R subsets matricesmatset[1, , , drop = TRUE, warn_class_change = FALSE]# you can obviously get some of the matrices onlymatset[,,1]matset[c(1,2),,1:2]# to showcase other kind of indexes. These are all equivalentsmatset[1,,]matset["r1", ,]matset[c(TRUE, FALSE), ,]matset[-2, ,] # equivalent because there are only 2 rows# this is also equivalentmatset[,,1]matset[[1]]