subsetting {matrixset}

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

x

matrixset object from which to extract element(s)

i, j

rows (i) and columns (j) to extract from matrices of x, as indices. These are either numeric or character values.

To extract every rows or columns, use i = NULL or j = NULL, which is the default for both. Note that treating NULL as empty differs from the usual extraction, where it is treated as integer(0).

Numeric values are coerced to integer through as.integer(), which means they are truncated towards zero.

Character vectors will be matched to the dimnames of the object.

Indices an also be logical vectors, stating for each element if it is extracted (TRUE) or rejected (FALSE). Logical vectors are NOT recycled, which is an important difference with usual matrix extraction. It means that the logical vector must match the object dimension in length.

Can also be negative integers, in which case they are indices of elements to leave out of the selection.

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 second column the j index.

matrix

index specifying matrix or matrices to extract. Index is numeric or character vectors or empty (NULL). Note that treating NULL as empty differs from the usual extraction, where it is treated as integer(0). Here a NULL (empty) results in selecting all matrices.

See arguments ⁠i,j⁠, as the same rules are followed.

drop

If TRUE, the drop option of matrix extraction is used. See [[()]. Note that the default for matrixset objects is FALSE.

keep_annotation

logical specifying if the resulting object should keep the annotations (meta info, or traits, as per matrixset notation) as part of the object. The default (TRUE), combined with the default drop = FALSE, guarantees that the resulting object is a matrixset object. If keep_annotation is FALSE, the resulting object will be a list of matrix, and a warning will be issued, unless warn_class_change is FALSE.

warn_class_change

logical that determines if a warning should be issued when the extraction result is not a matrixset. The default is to use the global option "matrixset.warn_class_change", which is FALSE by default. If one wants to silence permanently this warning, this is the option to change.

Details

Indexes i and j are given as for a regular matrix() (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 in unknown selection. Character indexes use exact matching, not partial.

The default arguments for "drop" and "keep_annotation" are chosen so that the object resulting from the extraction is still a matrixset.

Setting "keep_annotation" to FALSE automatically results in a class change (a list of matrix) and a warning is issued (see argument warn_class_change, however).

Setting drop to TRUE may also result to a change of class, depending on the provided indices (the same way matrix may result to a vector when drop is TRUE).

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

There is no $ subsetting operator for the matrixset object.

Value

The resulting object type depends on the subsetting options. By default, a matrixset object will be returned. This object will have the following properties:

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

• Annotations, or traits, are subsetted appropriately.

• The number of groups may be reduced.

• Currently, attributes are not preserved.

If keep_annotation is FALSE, the resulting object will be a list. Typically, it will be a list of matrix, but if drop is TRUE, some list elements could be vectors.

Grouped matrixset

When subsetting a grouped matrixset (by rows and/or columns), when the resulting object is still a matrixset, the grouping structure will be updated 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 again
matset[]

# 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 provided
matset[1, , ]

# similar idea
matset[,2, ]
matset[1,2,]

# it obviously works with vector indexes
matset[1:2, c(1,3),]

# you can extract the matrices this - even without the 'annoying' warning
matset[, , , 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 matrices
matset[1, , , drop = TRUE, warn_class_change = FALSE]

# you can obviously get some of the matrices only
matset[,,1]
matset[c(1,2),,1:2]

# to showcase other kind of indexes. These are all equivalents
matset[1,,]
matset["r1", ,]
matset[c(TRUE, FALSE), ,]
matset[-2, ,] # equivalent because there are only 2 rows

# this is also equivalent
matset[,,1]
matset[[1]]