CytoImageList-subsetting: General subsetting methods for CytoImageList objects

In BodenmillerGroup/cytomapper: Visualization of highly multiplexed imaging data in R

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 ([e-mail])

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

BodenmillerGroup/cytomapper documentation built on July 1, 2024, 3:45 p.m.