CytoImageList-subsetting {cytomapper} | R Documentation

## General subsetting methods for CytoImageList objects

### Description

These getter and setter functions are used to extract, replace and merge entries in a `CytoImageList` object.

### Arguments

`x, y` | `CytoImageList` objects
`i` | integer, logical, character or vector of such indicating which element(s) to replace or extract
`value` | a `CytoImageList` or `Image` object

### Value

A CytoImageList object

### Setting and getting images

Functions to extract and replace elements (= images) of a CytoImageList object. In the following code, `x` is a CytoImageList object. The parameter `i` indicates the element(s) of `x` that should be returned or replaced. Replacement is done by `value`, which takes a CytoImageList or Image object. If `length(i) > 0`, `value` has to be a CytoImageList object of `length(i)`, otherwise `value` allows a CytoImageList object of length 1 or an Image object. If an Image object is provided, only the image entry in the CytoImageList object is replaced, not the corresponding elementMetadata entry.

`getImages(x, i)`

  Returns image(s) indicated by `i` of the CytoImageList object `x`

`setImages(x, i) <- value`

  Replaces the image(s) indicated by `i` of the CytoImageList object `x` with `value`. For this, `value` needs to have the same length as `i`

These setter and getter functions are the recommended way of extracting and replacing images in a CytoImageList object. Alternatively, the standard operations via ``[``, ``[[``, ``[<-`` and ``[[<-`` can be performed (see `?List` for S4Vectors subsetting functionality). However, these operations do not change element names during replacment calls. The `setImages()` function makes sure that element names are replaced if `value` is named or if `i` is a character or vector of characters.

### Getting and setting channels

Functions to extract and replace channels of a CytoImageList object. Here, `x` is a CytoImageList object. The parameter `i` indicates the channels of `x` that should be returned or replaced. Replacement is done by `value`, which takes a CytoImageList object. The CytoImageList object `value` needs to have the same length as `x`. Furthermore, the number of channels in `value` should be identical to `length(i)`.

`getChannels(x, i)`

  Returns channel(s) indicated by `i` of the CytoImageList object `x`

`setChannels(x, i) <- value`

  Replaces the channel(s) indicated by `i` of the CytoImageList object `x` with `value`. For this, `value` needs to have the same length as `i` and the same number of channels as `length(i)`.

The `setChannels()` setter function does not allow adding new channels to the CytoImageList object. For this operation, the `mergeChannels` function was implemented (see below).

### Merging images

Merging images is possible by merging two or more CytoImageList objects via:

`c(x, y)`

  Returns an composite CytoImageList object with elements of both CytoImageList objects `x` and `y`. More than two CytoImageList objects can be merged in that way.

### Merging channels

Merging channels is possible via:

`mergeChannels(x, y, h5FilesPath = NULL)`:

  Returns a CytoImageList in which the channels of the CytoImageList object `y` have been appended to the channels of the CytoImageList object `x`. Only channels of two CytoImageList objects can be merged in that way. The `h5FilesPath` argument can be ignored unless images are stored on disk. To avoid overriding the .h5 files, one needs to specify a new location where the merged images are stored on disk.

### Author(s)

Nils Eling (nils.eling@dqbm.uzh.ch)

### Examples

    data("pancreasImages")

    # Get images
    getImages(pancreasImages, 1)
    getImages(pancreasImages, "E34_imc")
    getImages(pancreasImages, 1:2)
    getImages(pancreasImages, c("E34_imc", "G01_imc"))
    getImages(pancreasImages, grepl("E34_imc", names(pancreasImages)))

    # Set images
    setImages(pancreasImages, 1) <- pancreasImages[1]
    setImages(pancreasImages, "J02_imc") <- pancreasImages[1]
    setImages(pancreasImages, "J02_imc") <- NULL

    # Get channels
    getChannels(pancreasImages, 1)
    getChannels(pancreasImages, "CD99")
    getChannels(pancreasImages, c("CD99", "PIN"))

    # Set channels
    channel1 <- getChannels(pancreasImages, 1)
    setChannels(pancreasImages, 1) <- channel1
    channelPIN <- getChannels(pancreasImages, "PIN")
    setChannels(pancreasImages, "CD8a") <- channelPIN
    setChannels(pancreasImages, "CD8a") <- NULL

    # Merge images
    data("pancreasImages")
    c(pancreasImages[c(1,3)], pancreasImages[2])

    # Merge channels
    channel12 <- getChannels(pancreasImages, c(1,2))
    channel34 <- getChannels(pancreasImages, c(3,4))
    mergeChannels(channel12, channel34)

    # Merge channels on disk
    cur_images <- CytoImageList(pancreasImages,
                         on_disk = TRUE,
                         h5FilesPath = HDF5Array::getHDF5DumpDir())
    channel12 <- getChannels(cur_images, c(1,2))
    channel34 <- getChannels(cur_images, c(3,4))

    # This will overwrite the initial .h5 files
    mergeChannels(channel12, channel34,
                    h5FilesPath = HDF5Array::getHDF5DumpDir())

[Package cytomapper version 1.6.0 Index]