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`. 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 '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 object of class `SImageSet`.
`.fun` | The function to be applied.
`...` | Additional arguments passed to `.fun`.
`.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.
`.simplify` | Should the result be simplified into a matrix of higher-dimensional array rather than a list, if appropriate?
`.use.names` | Should the names of elements of `.object` (pixels, features, and grouping variables, as appropriate) be used for the names of the result?
`.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:

- `.Object`: The passed `.object`. (Note the case.)

- `.Index`: The index of the current iteration.

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 1.12.1 Index]