pixelApply-methods {Cardinal} | R Documentation |
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, ..., .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 'SparseImagingExperiment' spatialApply(.object, .r, .fun, ..., .dist = "chebyshev", .blocks = FALSE, .simplify = TRUE, .use.names = TRUE, .outpath = NULL, .params = NULL, .init = NULL, BPREDO = list(), BPPARAM = bpparam()) #### Methods for Cardinal 1.x classes #### ## 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)
.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 |
.dist |
The type of distance metric to use when calculating neighboring pixels based on |
.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 |
.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 |
.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 list of parameters with length equal to |
.init |
The initialization for the spatial neighbors and spatial blocks. If TRUE, then the result will have an attribute |
BPREDO |
See documentation for |
BPPARAM |
An optional instance of |
.pixel |
A subset of pixels to use, given by an |
.feature |
A subset of features to use, given in the same manner as pixels. |
.pixel.groups |
A grouping |
.feature.groups |
A grouping |
.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. |
#### 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
.
by
: A string giving either "pixel" for pixelApply
or "feature" for featureApply
. This attribute is to facilitate determining whether this is a call to pixelApply
or featureApply
within methods that may select one or the other to use depending on the internal data structure.
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).
params
: The relevant list elements of the .params
argument.
#### 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
register(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)