pixelApply-methods: Apply functions over imaging datasets
In Cardinal: A mass spectrometry imaging toolbox for statistical analysis

Description Usage Arguments Details Value Author(s) See Also Examples

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

#### Methods for Cardinal >= 2.x classes ####

## S4 method for signature 'SparseImagingExperiment'
pixelApply(.object, .fun, ...,
    .simplify = TRUE,
    .outpath = NULL,
    .params = list(),
    .blocks = getCardinalNumBlocks(),
    .verbose = getCardinalVerbose(),
    .view = "element",
    BPREDO = list(),
    BPPARAM = getCardinalBPPARAM())

## S4 method for signature 'SparseImagingExperiment'
featureApply(.object, .fun, ...,
    .simplify = TRUE,
    .outpath = NULL,
    .params = list(),
    .blocks = getCardinalNumBlocks(),
    .verbose = getCardinalVerbose(),
    .view = "element",
    BPREDO = list(),
    BPPARAM = getCardinalBPPARAM())

## S4 method for signature 'SparseImagingExperiment'
spatialApply(.object, .r, .fun, ...,
    .dist = "chebyshev",
    .simplify = TRUE,
    .outpath = NULL,
    .params = list(),
    .blocks = getCardinalNumBlocks(),
    .verbose = getCardinalVerbose(),
    .view = "element",
    BPREDO = list(),
    BPPARAM = getCardinalBPPARAM())

#### Methods for Cardinal 1.x classes ####

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

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

`.object`	An imaging dataset.
`.fun`	The function to be applied.
`.r`	The maximum spatial radius or distance for which pixels are considered to be neighbors.
`...`	Additional arguments passed to `.fun`.
`.dist`	The type of distance metric to use when calculating neighboring pixels based on `r`. The options are ‘radial’, ‘manhattan’, ‘minkowski’, and ‘chebyshev’ (the default).
`.blocks`	If FALSE (the default), each feature-vector or image-vector will be loaded and processed individually. If TRUE, or a positive integer, 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 `getCardinalNumBlocks()` will be used.
`.simplify`	If applying over blocks, then a function to be used to simplify the list of results. Otherwise, a logical value giving whether the results should be simplified into a matrix or array rather than a list.
`.use.names`	Should the names of elements of `.object` (either pixel names or feature names, 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.
`.params`	A named list of parameters with length equal to `length(.object)`. The appropriate elements will be made available to the spatial neighborhoods.
`.verbose`	Should progress messages be printed?
`.view`	FOR EXPERT USE ONLY: Should the object passed to `.fun` be a single element (e.g., one row/column/neighborhood of `.object`), or the entire block? Set to "chunk" to operate on the whole block.
`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.

#### For SparseImagingExperiment-derived classes ####

For pixelApply, the function is applied to the feature vector(s) belonging to pixel(s).

For featureApply, the function is applied to the vector(s) of intensity values (i.e., the flattened image) corresponding to the feature(s).

For spatialApply, the function is applied to neighborhoods of feature-vectors corresponding to neighboring pixels. The maximum distance in each dimension for a pixel to be considered a neighbor is given by .r. The first argument to .fun is a matrix of column-vectors.

If .blocks is provided (either TRUE or a positive integer), then the data is split into blocks beforehand, and entire blocks are loaded and passed to the function as a matrix of column-vectors. Otherwise, single vectors are passed to the function individually. If blocks are used, then .simplify should be a function that simplifies a list of results.

Note that for spatialApply (only), if blocks are used, the result is NOT guaranteed to be in the correct order; instead the result will have a attr(ans, "idx") attribute giving the proper order (pixel IDs) of the results, and the .simplify function should likely re-order the results.

The following attributes are assigned to the object passed to .fun, accessible via attr():

idx: The indices of the current pixel(s) or feature(s).
mcols: Either featureData(.object) for pixelApply or pixelData(.object) for featureApply.

Additionally, the following attributes are made available during a call to spatialyApply():

centers: A vector indicating which column(s) should be considered the center(s) of the neighborhood(s).
neighbors: A list of vectors indicating which column(s) should be considered the neighborhoods. Only relevant if using .blocks.
offsets: A matrix where the rows are the spatial offsets of the pixels in the neighborhood(s) from the center pixel(s).

Additionally, any named components of .params will also be provided as attributes, subsetted to the current element.

#### For SImageSet-derived classes ####

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:

.Object: The passed .object. (Note the case.)
.Index: The index of the current iteration.

If .simplify = FALSE, a list. Otherwise, a vector or matrix, or a higher-dimensional array if grouping is specified, or the output of the provided .simplify function.

Kylie A. Bemis

MSImagingExperiment, MSImageSet

setCardinalBPPARAM(SerialParam())

set.seed(2)
data <- simulateImage(preset=1, npeaks=10, dim=c(10,10))

# calculate TIC for each pixel
tic <- pixelApply(data, sum)

# calculate mean spectrum
ms <- featureApply(data, mean)