group_by {matrixset}

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

Description

Applying row_group_by() or column_group_by() to a matrixset object registers this object as one where certain operations are performed per (row or column) group.

To (partly) remove grouping, use row_ungroup() or column_ungroup().

These functions are the matrixset equivalent of dplyr's dplyr::group_by() and dplyr::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

.ms

A matrixset object

...

In row_group_by() or column_group_by(), annotation variables to use for grouping. These variables are the ones returned by row_traits() or column_traits(). In row_ungroup() or column_ungroup(), variables to remove from grouping. If not provided, grouping is removed altogether.

.add

logical. The default, FALSE, means that previous groups are overwritten. Setting .add to TRUE will add to the existing groups.

.drop

logical. When grouping by factor annotations, should levels that do not appear in the data be dropped? The default is TRUE, unless .ms has been previously grouped with .drop = FALSE.

Value

A grouped matrixset with class row_grouped_ms, unless .ms was already column-grouped via column_group_by(), in which case a dual_grouped_ms matrixset is returned.

If the combination of ... and .add yields an empty set of grouping columns, a regular matrixsetor a col_grouped_ms, as appropriate, will be returned.

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 listed
by_class

# Grouping changes how some functions operates
filter_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 grouping
row_group_vars(row_group_by(by_class, teacher))

# Use .add = TRUE to instead append
row_group_vars(row_group_by(by_class, teacher, .add = TRUE))
# To removing grouping, use ungroup
row_ungroup(by_class)