splitReduce {neuroim}

Generic function to summarize subsets of an object by first splitting by row and then "reducing" by a summary function

Description

Generic function to summarize subsets of an object by first splitting by row and then "reducing" by a summary function

Usage

splitReduce(x, fac, FUN)

## S4 method for signature 'matrix,integer,'function''
splitReduce(x, fac, FUN)

## S4 method for signature 'matrix,integer,missing'
splitReduce(x, fac)

## S4 method for signature 'matrix,factor,missing'
splitReduce(x, fac)

## S4 method for signature 'matrix,factor,'function''
splitReduce(x, fac, FUN)

## S4 method for signature 'BrainVector,factor,'function''
splitReduce(x, fac, FUN)

## S4 method for signature 'BrainVector,factor,missing'
splitReduce(x, fac, FUN)

Arguments

x

a numeric matrix(like) object

fac

the factor to define subsets of the object

FUN

the function to apply to each subset. if FUN is missing, than the mean of each sub-matrix column is computed.

Details

if FUN is supplied it must take a vector and return a single scalar value. If it returns more than one value, an error will occur.

if x is a BrainVector instance then voxels (dims 1:3) are treated as columns and time-series (dim 4) as rows. The summary function then is applied to groups of voxels. However, if the goal is to apply a function to groups of time-points, then this can be achieved as follows:

splitReduce(t(as.matrix(bvec)), fac)

Value

a new matrix where the original values have been reduced

Examples

mat = matrix(rnorm(100*100), 100, 100)
fac = sample(1:3, nrow(mat), replace=TRUE)
## compute column means of each sub-matrix
ms <- splitReduce(mat, fac)
all.equal(row.names(ms), levels(fac))

## compute column medians of each sub-matrix
ms <- splitReduce(mat, fac, median)

## compute time-series means grouped over voxels. 
## Here, \code{length(fac)} must equal the number of voxels: \code{prod(dim(bvec)[1:3]}
bvec <- BrainVector(array(rnorm(24*24*24*24), c(24,24,24,24)), BrainSpace(c(24,24,24,24), c(1,1,1)))
fac <- factor(sample(1:3, prod(dim(bvec)[1:3]), replace=TRUE))
ms <- splitReduce(bvec, fac)
ms2 <- splitReduce(bvec, fac, mean)
all.equal(row.names(ms), levels(fac))
all.equal(ms,ms2)