CellMix 1.6

Group Apply

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.

applyBy.matrix is a wrapper around colAvgsPerRowSet, which make the computation really fast, but requires somehow cumbersome matrix specifications for the groups of columns or rows. The wrapper builds the arguments for the particular case where the groups are defined by a factor.

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.

colBy computes for each column a given statistic within separate groups of rows, which are defined by a factor.

rowBy computes for each row a given statistic within separate groups of columns, which are defined by a factor.

Usage

applyBy(x, ...)

S3 (matrix)
`applyBy`(x, BY, MARGIN, FUN, W = NULL, ..., DROP = FALSE)

S3 (ExpressionSet)
`applyBy`(x, BY, MARGIN, ..., ANNOTATIONS = TRUE)

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

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

colSumsBy(x, BY, ...)

rowSumsBy(x, BY, ...)

rowMeansBy(x, BY, ...)

colMeansBy(x, BY, ...)

rowMediansBy(x, BY, ...)

colMediansBy(x, BY, ...)

rowMaxsBy(x, BY, ...)

colMaxsBy(x, BY, ...)

rowMinsBy(x, BY, ...)

colMinsBy(x, BY, ...)

Arguments

x
matrix-like object on which apply can be called.
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.
...
extra parameters passed to FUN.
DROP
logical that indicates if absent levels should be removed from the result matrix, or appear as 0-filled rows/columns.
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.
W
An optional numeric NxM matrix of weights.

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.

Examples


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

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

##            1      2
##  [1,] 1.9487 2.2151
##  [2,] 2.1763 2.3782
##  [3,] 1.4389 0.6221
##  [4,] 1.3251 1.2131
##  [5,] 2.3728 1.6890
##  [6,] 0.5697 1.5313
##  [7,] 1.7164 1.2575
##  [8,] 1.1916 0.8360
##  [9,] 1.4189 0.9605
## [10,] 1.7020 1.8783
## [11,] 2.1449 1.8523
## [12,] 1.7555 2.0532

# or
balt <- rowApplyBy(x, fc, rowSums)
identical(b, balt)

## [1] TRUE


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

## [1] TRUE

## Method for apply directly to ExpressionSet objects

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)

##   Group Sample
## 1     1      a
## 2     1      b
## 3     1      c
## 4     2      d
## 5     2      e
## 6     2      f

fData(x) <- data.frame(ENTREZID=fr, Gene=letters[nrow(x):1])
fData(x)

##    ENTREZID Gene
## 1         1    l
## 2         1    k
## 3         1    j
## 4         1    i
## 5         2    h
## 6         2    g
## 7         2    f
## 8         2    e
## 9         3    d
## 10        3    c
## 11        3    b
## 12        3    a


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

##   Group Sample
## 1     1      a
## 2     2      d

fData(y)

##    ENTREZID Gene
## 1         1    l
## 2         1    k
## 3         1    j
## 4         1    i
## 5         2    h
## 6         2    g
## 7         2    f
## 8         2    e
## 9         3    d
## 10        3    c
## 11        3    b
## 12        3    a


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

##   Group Sample
## 1     1      a
## 2     1      b
## 3     1      c
## 4     2      d
## 5     2      e
## 6     2      f

fData(y)

##   ENTREZID Gene
## 1        1    l
## 2        2    h
## 3        3    d