pixelApply-methods {Cardinal}R Documentation

Apply functions over imaging datasets

Description

Apply an existing or a user-specified function over either all of the features or all of the pixels of an SImageSet or SparseImagingExperiment. These are provided for convenience by analogy to the 'apply' family of functions, but allowing greater control over how the functions are applied over an imaging dataset.

Usage

## S4 method for signature 'SparseImagingExperiment'
pixelApply(.object, .fun, ...,
    .blocks = FALSE,
    .simplify = TRUE,
    .use.names = TRUE,
    .outpath = NULL,
    BPREDO = list(),
    BPPARAM = bpparam())

## S4 method for signature 'SparseImagingExperiment'
featureApply(.object, .fun, ...,
    .blocks = FALSE,
    .simplify = TRUE,
    .use.names = TRUE,
    .outpath = NULL,
    BPREDO = list(),
    BPPARAM = bpparam())

## S4 method for signature 'SImageSet'
pixelApply(.object, .fun, ...,
    .pixel,
    .feature,
    .feature.groups,
    .pixel.dependencies,
    .simplify = TRUE,
    .use.names = TRUE,
    .verbose = FALSE)

## S4 method for signature 'SImageSet'
featureApply(.object, .fun, ...,
    .feature,
    .pixel,
    .pixel.groups,
    .feature.dependencies,
    .simplify = TRUE,
    .use.names = TRUE,
    .verbose = FALSE)

Arguments

.object

An imaging dataset.

.fun

The function to be applied.

...

Additional arguments passed to .fun.

.blocks

If FALSE (the default), each feature-vector or image-vector will be loaded and processed individually. If TRUE, or a number, the data will be split into that many blocks, and the function (specified by .fun) will be applied to each block. The number of blocks can be specified as a number, or getOption("Cardinal.nblocks") will be used.

.simplify

Should the result be simplified into a matrix or array rather than a list, if appropriate?

.use.names

Should the names of elements of .object (pixels or features, as appropriate) be used for the names of the result?

.outpath

The path to a file where the output data will be written. Results will be kept in-memory if this is NULL. Results will be coerced to a numeric vector before being written to file.

BPREDO

See documentation for bplapply.

BPPARAM

An optional instance of BiocParallelParam. See documentation for bplapply.

.pixel

A subset of pixels to use, given by an integer vector of numeric indices, a character vector of pixel names, or a logical vector indicating which pixels to use.

.feature

A subset of features to use, given in the same manner as pixels.

.pixel.groups

A grouping factor or a vector that can be coerced into a factor, that indicates groups of pixels over which the function should be applied. Groups pixels are treated as cells in a ragged array, by analogy to the tapply function.

.feature.groups

A grouping factor features, in the same manner as for pixels.

.pixel.dependencies

Not currently used. This may be used in the future to allow caching when applying functions to data on disk.

.feature.dependencies

Not currently used. May be used for caching in the future.

.verbose

Used for debugging. Currently ignored.

Details

The use of .pixel and .feature can be used to apply the function over only a subset of pixels or features (or both), allowing faster computation when calculation on only a subset of data is needed.

For pixelApply, the function is applied to the feature vector belonging to each pixel. The use of .feature.groups allows codetapply-like functionality on the feature vectors, applied separately to each pixel.

For featureApply, the function is applied to the vector of intensity values (i.e., the flattened image) corresponding to each feature. The use of .feature.groups allows codetapply-like functionality on the flattened image intensity vectors, applied separately to each feature.

The fData from .object is installed into the environment of .fun for pixelApply, and the pData from .object is installed into the environment of .fun for featureApply. This allows access to the symbols from fData or pData during the execution of .fun. If .fun already has an environment, it is retained as the parent of the installed environment.

Additionally, the following objects are made available by installing them into the .fun environment:

It is expected that these methods will be expanded in the future for different types of imaging datasets (e.g., data read directly from disk).

Value

If .simplify = FALSE, a list. Otherwise, a matrix, or a higher-dimensional array if grouping is specified.

Author(s)

Kylie A. Bemis

See Also

MSImageSet

Examples

data <- matrix(1:256, nrow=4)
coord <- expand.grid(x=1:4, y=1:4, z=1:4)
sset <- SImageSet(data=data, coord=coord)

fData(sset)$flag <- rep(c(TRUE, FALSE), 2)
pixelApply(sset, max, .feature.groups=flag)

pData(sset)$flag <- rep(c(TRUE, FALSE), 32)
featureApply(sset, max, .pixel.groups=flag)

[Package Cardinal version 2.0.4 Index]