loadImages: Read images into CytoImageList object

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

Read images into CytoImageList object

Description

Function to read in single- or multi-channel images from a specified path or file. The function returns a CytoImageList object containing one image per slot. Supported file extensions are: '.tiff', '.tif', '.png', '.jpeg', '.jpg', ".h5".

Usage

loadImages(
  x,
  pattern = NULL,
  single_channel = FALSE,
  on_disk = FALSE,
  h5FilesPath = NULL,
  name = NULL,
  BPPARAM = SerialParam(),
  ...
)

Arguments

x	The function takes a variety of possible character inputs: A single file Full path and file name of an individual image file. A path A path to where image files are located. A vector of files A character vector where each entry represents an individual file.
pattern	Character inputs of the following form: A single character A pattern to search for in the specified path (regular expressions are supported). A character vector Unique entries are matched against file names in the specified path.
single_channel	logical indicating if each file per folder contains a single channel. These files will be read in and stitched together to form a single multi-channel image. For this, x needs to be a single path either containing individual files or sub-paths containing those.
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()
name	(if reading in .h5 files) a single character, a character vector of length equal to the length of x or NULL. See details for how to set name.
BPPARAM	parameters for parallelised reading in of images. This is only recommended for very large images. See MulticoreParam for information on how to use multiple cores for parallelised processing.
...	arguments passed to the readImage function.

Value

A CytoImageList object

Reading in 16-bit integer images

To correctly read in the original integer values of 16-bit, the as.is = TRUE parameter needs to be added to the function call. This will prevent the readTIFF function to re-scale integer values.

Loading specific images

This function loads images via the readImage function and stores them in a CytoImageList object. In the simplest case, x is an image file name. If x is a path, the pattern argument can be used to select image names with certain patterns. For convenience, pattern also takes a vector of characters (e.g. a colData entry in a SingleCellExperiment object) to select by unique image names. Furthermore, a vector of image names can be provided to read in multiple images.

Reading in .h5 files

When reading in .h5 files by default the loadImages function will try to read in the dataset with the same name as the .h5 file from within the file. If datasets are stored with different names, the name argument must be specified. This can either be a single character if datasets across all files are named the same or a character vector of the same length as x indicating the dataset name within each .h5 file. By default, the images/datasets are not read into memory when stored in .h5 files.

Author(s)

Nils Eling ([e-mail]),

Nicolas Damond ([e-mail])

See Also

readImage, for reading in individual images.

Examples

# Providing a single file
single.image <- system.file("extdata/E34_mask.tiff", package = "cytomapper")
single.image <- loadImages(single.image)

# Providing a path and pattern
path.to.images <- system.file("extdata", package = "cytomapper")
image.list <- loadImages(path.to.images, pattern = "mask.tiff")

# Providing multiple patterns
data(pancreasSCE)
path.to.images <- system.file("extdata", package = "cytomapper")
image.list <- loadImages(path.to.images, pattern = pancreasSCE$MaskName)

# Providing multiple files
list.images <- list.files(system.file("extdata", package = "cytomapper"),
                            pattern = "_mask.tiff", full.names = TRUE)
image.list <- loadImages(list.images)

# On disk representation
path.to.images <- system.file("extdata", package = "cytomapper")
image.list <- loadImages(path.to.images, pattern = "mask.tiff",
                            on_disk = TRUE, 
                            h5FilesPath = HDF5Array::getHDF5DumpDir())
                            
# Parallel processing
path.to.images <- system.file("extdata", package = "cytomapper")
image.list <- loadImages(path.to.images, pattern = "mask.tiff",
                            BPPARAM = BiocParallel::MulticoreParam())

BodenmillerGroup/SingleCellMapper documentation built on March 26, 2024, 1:09 a.m.