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".
loadImages(
x,
pattern = NULL,
single_channel = FALSE,
on_disk = FALSE,
h5FilesPath = NULL,
name = NULL,
BPPARAM = SerialParam(),
...
)The function takes a variety of possible character inputs:
Full path and file name of an individual image file.
A path to where image files are located.
A character vector where each entry represents an individual file.
Character inputs of the following form:
A pattern to search for in the specified path (regular expressions are supported).
Unique entries are matched against file names in the specified path.
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.
Logical indicating if images in form of HDF5Array objects (as .h5 files) should be stored on disk rather than in memory.
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()
(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.
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.
A CytoImageList object
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.
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.
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.
readImage, for reading in individual images.
# 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())