R/subsetting-utils.R
CytoImageList-subsetting.RdThese getter and setter functions are used to extract, replace and merge
entries in a CytoImageList object.
CytoImageList objects
integer, logical, character or vector of such indicating which element(s) to replace or extract
a CytoImageList or Image
object
A CytoImageList object
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) <- valueReplaces 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.
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) <- valueReplaces 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 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 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.
data("pancreasImages")
# Get images
getImages(pancreasImages, 1)
#> CytoImageList containing 1 image(s)
#> names(1): E34_imc
#> Each image contains 5 channel(s)
#> channelNames(5): H3 CD99 PIN CD8a CDH
getImages(pancreasImages, "E34_imc")
#> CytoImageList containing 1 image(s)
#> names(1): E34_imc
#> Each image contains 5 channel(s)
#> channelNames(5): H3 CD99 PIN CD8a CDH
getImages(pancreasImages, 1:2)
#> CytoImageList containing 2 image(s)
#> names(2): E34_imc G01_imc
#> Each image contains 5 channel(s)
#> channelNames(5): H3 CD99 PIN CD8a CDH
getImages(pancreasImages, c("E34_imc", "G01_imc"))
#> CytoImageList containing 2 image(s)
#> names(2): E34_imc G01_imc
#> Each image contains 5 channel(s)
#> channelNames(5): H3 CD99 PIN CD8a CDH
getImages(pancreasImages, grepl("E34_imc", names(pancreasImages)))
#> CytoImageList containing 1 image(s)
#> names(1): E34_imc
#> Each image contains 5 channel(s)
#> channelNames(5): H3 CD99 PIN CD8a CDH
# Set images
setImages(pancreasImages, 1) <- pancreasImages[1]
setImages(pancreasImages, "J02_imc") <- pancreasImages[1]
setImages(pancreasImages, "J02_imc") <- NULL
# Get channels
getChannels(pancreasImages, 1)
#> CytoImageList containing 2 image(s)
#> names(2): E34_imc G01_imc
#> Each image contains 1 channel(s)
#> channelNames(1): H3
getChannels(pancreasImages, "CD99")
#> CytoImageList containing 2 image(s)
#> names(2): E34_imc G01_imc
#> Each image contains 1 channel(s)
#> channelNames(1): CD99
getChannels(pancreasImages, c("CD99", "PIN"))
#> CytoImageList containing 2 image(s)
#> names(2): E34_imc G01_imc
#> Each image contains 2 channel(s)
#> channelNames(2): 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])
#> Error: subscript contains out-of-bounds indices
# Merge channels
channel12 <- getChannels(pancreasImages, c(1,2))
channel34 <- getChannels(pancreasImages, c(3,4))
mergeChannels(channel12, channel34)
#> CytoImageList containing 2 image(s)
#> names(2): E34_imc G01_imc
#> Each image contains 4 channel(s)
#> channelNames(4): H3 CD99 PIN CDH
# 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())
#> CytoImageList containing 2 image(s)
#> names(2): E34_imc G01_imc
#> Each image contains 4 channel(s)
#> channelNames(4): H3 CD99 PIN CDH