# On disk storage and handling of images

# Introduction

HDF5Array and DelayedArray are convenient Bioconductor packages to work with arrays “on disk” instead of “in memory”. The `cytomapper` package builds upon these tools to allow storing image data on disk. While this facilitates the handling of hundreds to thousand of images in parallel, little changes are experienced from the user perspective. Here, we explain which `cytomapper` function are effected by storing images on disk.

# Reading in data to disk

The `loadImages` function takes extra arguments to specify if images should be stored on disk (`on_disk`) and where to store them (`h5FilesPath`). When images should be stored for longer than the current R session, the `h5FilesPath` needs to be set to a permanent directory. The `HDF5Array` package provides the `getHDF5DumpDir` function, which initialize a temporary directory, which will be deleted once the session closes. This is what we will use here for demonstration purposes.

    library(HDF5Array)

    # Define output directory
    cur_dir <- getHDF5DumpDir()

    path.to.images <- system.file("extdata", package = "cytomapper")
    image.list <- loadImages(path.to.images, pattern = "mask.tiff",
                                 on_disk = TRUE, h5FilesPath = cur_dir)

    # Show list
    image.list

    ## CytoImageList containing 3 image(s)
    ## names(3): E34_mask G01_mask J02_mask
    ## Each image contains 1 channel

    # Scale images
    image.list <- scaleImages(image.list, value = 2^16 - 1)
    image.list$E34_mask

    ## <100 x 100> DelayedMatrix object of type "double":
    ##          [,1]   [,2]   [,3] ...  [,99] [,100]
    ##   [1,]    824    824    824   .   1265   1265
    ##   [2,]    824    824    824   .   1265      0
    ##   [3,]    824    824    824   .      0      0
    ##   [4,]    824    824    824   .      0   1295
    ##   [5,]    824    824    824   .      0   1295
    ##    ...      .      .      .   .      .      .
    ##  [96,]    835      0    876   .      0      0
    ##  [97,]    835      0    876   .      0      0
    ##  [98,]    835      0    876   .   1293   1293
    ##  [99,]      0      0    876   .   1293   1293
    ## [100,]      0      0      0   .   1293   1293

This function call reads in the .tiff images before writing them as .h5 files to the indicated directory. It generates a `CytoImageList` object that contains `HDF5Array` or `DelayedArray` objects (instead of `Image` objects) in each slot, which references the data in the .h5 files. The name of the array within the .h5 file is automatically set as the original filename and cannot be changed easily from within R. Writing the images to disk is slow and therefore less efficient compared to keeping images in memory. However, when working with hundreds of images in parallel, all images remain accessible from within the R session if they are stored on disk. In conclusion: when working with small image sets it is recommended reading them into memory (`on_disk = FALSE`, default), while large image sets should be written to disk (`on_disk = TRUE`). When reading in the same images multiple times, the .h5 files will always be replaced.

Please follow the main vignette for instructions on how to work with multi-channel images in R.

# Converting from on disk to memory and back

Existing `CytoImageList` objects, which contain individual `Image` objects in memory can be converted into `CytoImageList` objects storing `DelayedArray` or `HDF5Array` objects on disk. For this the following function calls can be used:

    data("pancreasImages")

    pancreasImages_onDisk <- CytoImageList(pancreasImages,
                                            on_disk = TRUE,
                                            h5FilesPath = cur_dir)

    # Image object
    pancreasImages$E34_imc

    ## Image
    ##   colorMode    : Grayscale
    ##   storage.mode : double
    ##   dim          : 100 100 5
    ##   frames.total : 5
    ##   frames.render: 5
    ##
    ## imageData(object)[1:5,1:6,1]
    ##           [,1]      [,2]         [,3]      [,4]         [,5]         [,6]
    ## [1,] 2.2357869 0.2537275 1.269632e+00 0.9991982 1.990020e+00 0.000000e+00
    ## [2,] 2.8855283 1.9900196 2.264642e+00 0.0000000 1.410924e+00 5.654589e-16
    ## [3,] 3.4009433 0.9950098 9.950098e-01 2.1800663 4.152935e-17 1.990020e+00
    ## [4,] 3.2238317 3.1750760 1.128341e+00 4.4866042 7.371460e-16 0.000000e+00
    ## [5,] 0.9987666 1.9900196 2.644036e-15 0.0000000 0.000000e+00 1.523360e+00

    # HDF5Array object
    pancreasImages_onDisk$E34_imc

    ## <100 x 100 x 5> HDF5Array object of type "double":
    ## ,,H3
    ##             [,1]      [,2]      [,3] ...     [,99]    [,100]
    ##   [1,] 2.2357869 0.2537275 1.2696325   .  7.265561  1.975094
    ##   [2,] 2.8855283 1.9900196 2.2646422   .  2.985029  2.885528
    ##    ...         .         .         .   .         .         .
    ##  [99,]  2.985029  3.636569 22.976585   . 25.371881 12.045588
    ## [100,]  3.061645  2.985029  1.990020   . 13.353615  5.636652
    ##
    ## ...
    ##
    ## ,,CDH
    ##             [,1]      [,2]      [,3] ...    [,99]   [,100]
    ##   [1,]  0.940284 19.651394 43.284626   . 2.704231 0.000000
    ##   [2,]  8.393239 29.353861 22.249359   . 7.345311 5.781126
    ##    ...         .         .         .   .        .        .
    ##  [99,] 0.9897148 7.3378549 0.0000000   . 0.000000 1.667201
    ## [100,] 5.8091230 2.2515676 1.9969171   . 4.344125 0.000000

    # Seed of HDF5Array object
    seed(pancreasImages_onDisk$E34_imc)

    ## An object of class "HDF5ArraySeed"
    ## Slot "filepath":
    ## [1] "/tmp/Rtmp2DgtKp/HDF5Array_dump/E34_imc.h5"
    ##
    ## Slot "name":
    ## [1] "/E34_imc"
    ##
    ## Slot "as_sparse":
    ## [1] FALSE
    ##
    ## Slot "type":
    ## [1] NA
    ##
    ## Slot "dim":
    ## [1] 100 100   5
    ##
    ## Slot "chunkdim":
    ## [1] 100 100   5
    ##
    ## Slot "first_val":
    ## [1] 2.235787

    # Size in memory
    format(object.size(pancreasImages), units = "auto")

    ## [1] "1.2 Mb"

    format(object.size(pancreasImages_onDisk), units = "auto")

    ## [1] "11.8 Kb"

Images can also be moved back to in memory representation:

    pancreasImages_inMemory <- CytoImageList(pancreasImages_onDisk,
                                            on_disk = FALSE)

    # Compare the image data to the original representation
    identical(as.list(pancreasImages_inMemory), as.list(pancreasImages))

    ## [1] TRUE

# Effects on package functionality

While most functions of the `cytomapper` package natively support images stored on disk, there are three exceptions: the `normalize`, `setChannels` and `mergeChannels` functions.

The `normalize` function will store the normalized images as a second dataset in the same .h5 file as the original data.

    # Size of object in memory
    format(object.size(pancreasImages_onDisk), units = "auto")

    ## [1] "11.8 Kb"

    # Size of object on disk in kB
    file.info(paste0(cur_dir, "/E34_imc.h5"))[,"size"] / 1000

    ## [1] 148.147

    pancreasImages_norm <- normalize(pancreasImages_onDisk)

    seed(pancreasImages_norm$E34_imc)

    ## An object of class "HDF5ArraySeed"
    ## Slot "filepath":
    ## [1] "/tmp/Rtmp2DgtKp/HDF5Array_dump/E34_imc.h5"
    ##
    ## Slot "name":
    ## [1] "/E34_imc_norm"
    ##
    ## Slot "as_sparse":
    ## [1] FALSE
    ##
    ## Slot "type":
    ## [1] NA
    ##
    ## Slot "dim":
    ## [1] 100 100   5
    ##
    ## Slot "chunkdim":
    ## [1] 100 100   5
    ##
    ## Slot "first_val":
    ## [1] 0.01235403

    # Size of object in memory
    format(object.size(pancreasImages_norm), units = "auto")

    ## [1] "11.8 Kb"

    # Size of object on disk in kB
    file.info(paste0(cur_dir, "/E34_imc.h5"))[,"size"] / 1000

    ## [1] 414.936

As we can see, the size in memory does not increase when normalizing images. However, the size on disk increases since a second, normalized dataset is stored in the .h5 file. The original dataset can be overwritten by setting `overwrite = TRUE` to save space on disk. This will however break the links to the original data in all R objects. It is therefore recommended leaving the default `overwrite = FALSE`. Furthermore, the normalization of images stored on disk is slower compared to normalizing images in memory since normalized images need to be written to disk.

The `setChannels` function replaces the same channels in all images by a user defined channel. There is no problem with this when keeping images in memory. However, the `DelayedArray` framework stores the replacement value in subassignemt operations in memory. This means that when using the `setChannels` function, the size of the object increases in memory usage:

    cur_Images1 <- pancreasImages_onDisk
    cur_Images2 <- getChannels(pancreasImages_onDisk, 2)
    channelNames(cur_Images2) <- "CD99_2"

    setChannels(cur_Images1, 1) <- cur_Images2
    format(object.size(cur_Images1), units = "auto")

    ## [1] "27.2 Kb"

The `mergeChannels` function merges multiple user-defined channels. As this operation creates a completely new image object, one needs to store the merged channels in a different location:

    channels1 <- getChannels(pancreasImages_onDisk, 1:2)
    channels2 <- getChannels(pancreasImages_onDisk, 3:4)

    dir.create(file.path(cur_dir, "test"))
    cur_path_2 <- file.path(cur_dir, "test")

    channels3 <- mergeChannels(channels1, channels2,
                                h5FilesPath = cur_path_2)

    seed(channels3$E34_imc)

    ## An object of class "HDF5ArraySeed"
    ## Slot "filepath":
    ## [1] "/tmp/Rtmp2DgtKp/HDF5Array_dump/test/E34_imc.h5"
    ##
    ## Slot "name":
    ## [1] "/E34_imc"
    ##
    ## Slot "as_sparse":
    ## [1] FALSE
    ##
    ## Slot "type":
    ## [1] NA
    ##
    ## Slot "dim":
    ## [1] 100 100   4
    ##
    ## Slot "chunkdim":
    ## [1] 100 100   4
    ##
    ## Slot "first_val":
    ## [1] 2.235787

# Session info

    ## R version 4.6.0 (2026-04-24)
    ## Platform: x86_64-pc-linux-gnu
    ## Running under: Ubuntu 24.04.4 LTS
    ##
    ## Matrix products: default
    ## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    ## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    ##
    ## locale:
    ##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    ##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
    ##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    ##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    ##  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    ## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    ##
    ## time zone: Etc/UTC
    ## tzcode source: system (glibc)
    ##
    ## attached base packages:
    ## [1] stats4    stats     graphics  grDevices utils     datasets  methods
    ## [8] base
    ##
    ## other attached packages:
    ##  [1] HDF5Array_1.41.0            h5mread_1.5.0
    ##  [3] rhdf5_2.57.1                DelayedArray_0.39.3
    ##  [5] SparseArray_1.13.2          S4Arrays_1.13.0
    ##  [7] abind_1.4-8                 Matrix_1.7-5
    ##  [9] cytomapper_1.25.0           SingleCellExperiment_1.35.1
    ## [11] SummarizedExperiment_1.43.0 Biobase_2.73.1
    ## [13] GenomicRanges_1.65.0        Seqinfo_1.3.0
    ## [15] IRanges_2.47.2              S4Vectors_0.51.3
    ## [17] BiocGenerics_0.59.6         generics_0.1.4
    ## [19] MatrixGenerics_1.25.0       matrixStats_1.5.0
    ## [21] EBImage_4.55.0              BiocStyle_2.41.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] tidyselect_1.2.1         viridisLite_0.4.3        vipor_0.4.7
    ##  [4] dplyr_1.2.1              farver_2.1.2             viridis_0.6.5
    ##  [7] S7_0.2.2                 bitops_1.0-9             fastmap_1.2.0
    ## [10] RCurl_1.98-1.18          promises_1.5.0           digest_0.6.39
    ## [13] mime_0.13                lifecycle_1.0.5          terra_1.9-27
    ## [16] magrittr_2.0.5           compiler_4.6.0           rlang_1.2.0
    ## [19] sass_0.4.10              tools_4.6.0              yaml_2.3.12
    ## [22] knitr_1.51               htmlwidgets_1.6.4        sp_2.2-1
    ## [25] RColorBrewer_1.1-3       BiocParallel_1.47.0      sys_3.4.3
    ## [28] grid_4.6.0               xtable_1.8-8             Rhdf5lib_2.1.0
    ## [31] ggplot2_4.0.3            scales_1.4.0             cli_3.6.6
    ## [34] rmarkdown_2.31           otel_0.2.0               rjson_0.2.23
    ## [37] ggbeeswarm_0.7.3         cachem_1.1.0             nnls_1.6
    ## [40] parallel_4.6.0           BiocManager_1.30.27      XVector_0.53.0
    ## [43] tiff_0.1-12              vctrs_0.7.3              jsonlite_2.0.0
    ## [46] fftwtools_0.9-11         beeswarm_0.4.0           systemfonts_1.3.2
    ## [49] jpeg_0.1-11              maketools_1.3.2          magick_2.9.1
    ## [52] locfit_1.5-9.12          jquerylib_0.1.4          glue_1.8.1
    ## [55] codetools_0.2-20         gtable_0.3.6             raster_3.6-32
    ## [58] later_1.4.8              shinydashboard_0.7.3     svgPanZoom_0.3.4
    ## [61] tibble_3.3.1             pillar_1.11.1            htmltools_0.5.9
    ## [64] rhdf5filters_1.25.0      R6_2.6.1                 textshaping_1.0.5
    ## [67] evaluate_1.0.5           shiny_1.13.0             lattice_0.22-9
    ## [70] png_0.1-9                SpatialExperiment_1.23.0 httpuv_1.6.17
    ## [73] bslib_0.11.0             Rcpp_1.1.1-1.1           gridExtra_2.3
    ## [76] svglite_2.2.2            xfun_0.57                buildtools_1.0.0
    ## [79] pkgconfig_2.0.3

# References