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 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.

### Usage

    #### 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)

### Arguments

`.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.

### Details

#### 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.

### Value

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.

### Author(s)

Kylie A. Bemis

### See Also

`MSImagingExperiment`, `MSImageSet`

### Examples

    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)

[Package Cardinal version 2.12.0 Index]