CytoImageList-class {cytomapper} | R Documentation

## S4 class for list of images

### Description

This class facilitates the handling of multiple one- or multi-channel images. It inherits from `SimpleList` setting `elementType="Image"`. Therefore, each slot contains an either one- or multi-dimensional array in form of an `Image` object.

### Usage

    CytoImageList(
      ...,
      on_disk = FALSE,
      h5FilesPath = NULL,
      BPPARAM = SerialParam()
    )

### Arguments

`...` | A list of images (or coercible to a list) or individual images
`on_disk` | Logical indicating if images in form of HDF5Array objects (as .h5 files) should be stored on disk rather than in memory.
`h5FilesPath` | path to where the .h5 files for on disk representation are stored. This path needs to be defined when `on_disk = TRUE`. When files should only temporarily be stored on disk, please set `h5FilesPath = getHDF5DumpDir()`
`BPPARAM` | parameters for parallelised processing. This is only recommended for very large images. See `MulticoreParam` for information on how to use multiple cores for parallelised processing.

### Details

Similar to the `Image` class, the first two dimensions of each entry indicate the spatial dimension of the image. These can be different for each entry. The third dimension indicates the number of channels per Image. Each entry in the CytoImageList class object must contain the same number of channels. Here, each channel represents pixel values indicating measurement intensities or in case of segmentation masks the cells' ID. The CytoImageList class therefore only supports a Grayscale colormode (see `colormode`) representation of each individual image.

The class further contains an `elementMetadata` slot that stores image-level meta information. This slot should be accessed using the `mcols` accessor function.

### Value

A CytoImageList object

### Restrictions on entry names

The CytoImageList class only supports unique entry names to avoid duplicated images. Names of a CytoImageList object can be get and set via `names(x)`, where `x` is a CytoImageList object. Furthermore, only named or unnamed CytoImageList objects are allowed. Partially named objects causing empty or NA names return an error.

### Coercion

Coercion to and from list, `SimpleList` and `List`:

as.list(x), as(x, "SimpleList"), as(x, "SimpleList"):

  Coercion from a CytoImageList object `x`

as(x, "CytoImageList"):

  Coercion from a list, SimpleList or List object `x` to anCytoImageList object

### Looping

While `lapply` and `mapply` return regular list objects, `endoapply` and `mendoapply` return CytoImageList objects.

### On disk representation

When setting `on_disk = TRUE` and specifying the `h5FilesPath`, images are stored on disk. To convert back to an in-memory `CytoImageList` object, one can call `CytoImageList(on_disk_IL, on_disk = FLASE)`.

### Author(s)

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

### See Also

`Image`, for further image analysis tools.

`SimpleList`, for basics functions to handle SimpleList objects

`?loadImages`, for reading images into a CytoImageList object

`?"CytoImageList-naming"`, for setting and getting image and channel names

`?"CytoImageList-subsetting"`, for subsetting and accessor functions

### Examples

    # Creation of CytoImageList
    u <- matrix(rbinom(100, 10, 0.5), ncol=10, nrow=10)
    v <- matrix(rbinom(100, 10, 0.5), ncol=10, nrow=10)
    IL1 <- CytoImageList(image1 = Image(u), image2 = Image(v))

    # Coercion
    as.list(IL1)
    as(IL1, "SimpleList")
    as(list(image1 = Image(u), image2 = Image(v)), "CytoImageList")

    # On disk representation
    IL1 <- CytoImageList(image1 = Image(u), image2 = Image(v),
                         on_disk = TRUE,
                         h5FilesPath = HDF5Array::getHDF5DumpDir())

[Package cytomapper version 1.4.1 Index]