applyBy: Group Apply

In renozao/applyBy: Subset-wise apply functions to aggregate rows or columns of matrix-like objects

Description

appplyBy is an S3 generic function that applies a given function to sub-matrices of a matrix-like object, which are generated according to a factor that defines groups rows or columns.

In essence, applyBy.matrix is a wrapper around colAvgsPerRowSet and rowAvgsPerColSet from the matrixStats package, which makes the computation really fast, but requires somehow cumbersome matrix arguments to specify the groups of columns or rows. The wrapper function builds the required arguments for cases where the groups are defined by a factor or a list of indexes.

A method is provided for ExpressionSet objects, which preserve sample and feature annotations. Moreover it allows directly passing names of feature/sample annotation – factor – variables in argument BY (see examples).

rowApplyBy applies a function to rows of sub-matrices whose columns are defined by a factor.

rowApplyBy applies a function to columns of sub-matrices whose rows are defined by a factor.

Usage

applyBy(x, ...)

## S3 method for class 'matrix'
applyBy(x, BY, MARGIN, FUN, W = NULL, ..., DROP = FALSE,
  DUPS = NULL)

## S3 method for class 'ExpressionSet'
applyBy(x, BY, MARGIN, ..., ANNOTATIONS = TRUE)

## S3 method for class 'numeric'
applyBy(x, BY, MARGIN, ...)

rowApplyBy(x, BY, FUN, ...)

colApplyBy(x, BY, FUN, ...)

Arguments

x	matrix-like object on which apply can be called.
...	extra parameters passed to FUN.
BY	factor or object coerced to a factor, that defines the groups within which the function FUN is applied. If x is an ExpressionSet object, then BY can be the names of a sample (resp. feature) annotation variable if MARGIN=1 (resp. MARGIN=2L) (see examples).
MARGIN	margin along which the function FUN is applied: 1L for rows, 2L for columns.
FUN	function to apply to each sub-matrix that contains the rows/columns defined by each level of argument BY. It must be a function that takes a matrix as its first argument and returns a vector of length the dimension of margin MARGIN of x.
W	An optional numeric NxM matrix of weights.
DROP	logical that indicates if absent levels should be removed from the result matrix, or appear as 0-filled rows/columns. If BY is a list of character indexes, then DROP=FALSE will complete the list with any missing index, so that the corresponding rows/columns form singletons. This means that these data will be passed as row/column vectors to the aggregation function FUN.
DUPS	logical, used when BY is a list, that indicates if overlapping sets are allowed. Default is to throw a warning if such case is detected. Using DUPS = TRUE silence the warning, while DUPS = FALSE turns into an error.
ANNOTATIONS	logical that indicates if samples/feature annotations should be kept, when the input data is an ExpressionSet object. Currently, if TRUE: if codeMARGIN=1L, then feature annotations are kept unchanged, and phenotypic sample annotations are discarded. if codeMARGIN=2L, then phenotypic sample annotations are kept unchanged, and feature annotations are discarded. In any case, the value of slot annotation (i.e. the annotation package), is passed on to the result object.

Value

The result is a matrix or an ExpressionSet object whose margin's dimension MARGIN is equal the same margin's dimension in x, and the other to the number of levels in BY.

See Also

built-ins

Examples

# random data matrix
x <- matrix(runif(12 * 6), 12, 6)

# by groups of columns
fc <- gl(2, 3)
b <- applyBy(x, fc, 1L, rowSums)
b
# or
balt <- rowApplyBy(x, fc, rowSums)
stopifnot(identical(b, balt))

# by groups of rows
fr <- gl(3, 4)
b <- applyBy(x, fr, 2L, colSums)
# or
balt <- colApplyBy(x, fr, colSums)
stopifnot(identical(b, balt))

## Method for apply directly to ExpressionSet objects

library(Biobase)
x <- ExpressionSet(x, annotation='abcd.db')
y <- rowMinsBy(x, fc)
y <- colMinsBy(x, fr)

## annotations are conserved/collapsed
pData(x) <- data.frame(Group=fc, Sample=letters[1:ncol(x)])
pData(x)
fData(x) <- data.frame(ENTREZID=fr, Gene=letters[nrow(x):1])
fData(x)

# keep feature annotations, collapse sample annotations
y <- rowMinsBy(x, 'Group')
pData(y)
fData(y)

# keep sample annotations, collapse feature annotations
y <- colMinsBy(x, 'ENTREZID')
pData(y)
fData(y)

x <- runif(12)
# 3 groups of 4 elements
g <- gl(3, 4)
g

# row means ~> row matrix with 3 columns
a <- rowMeansBy(x, g)
a
# col means ~> column matrix with 3 rows
b <- colMeansBy(x, g)
b

# values are identical
stopifnot( identical(as.numeric(a), as.numeric(b)) )

renozao/applyBy documentation built on May 27, 2019, 5:53 a.m.