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

### 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 `getOption("Cardinal.nblocks")` 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 list of parameters with length equal to `length(.object)`. The appropriate elements will be made available to the spatial neighborhoods.
`.init` | The initialization for the spatial neighbors and spatial blocks. If TRUE, then the result will have an attribute `attr(ans, "init")` that can be used as input to `.init` in future calls to avoid re-calculating spatial neighbors and spatial blocks.
`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

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

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

    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)

[Package Cardinal version 2.4.0 Index]