writeImage: Write image to disk

In theMILOlab/SPATA2: A Toolbox for Spatial Expression Analysis

Write image to disk

Description

Writes an image to a specified directory.

Usage

writeImage(object, ...)

## S4 method for signature 'SPATA2'
writeImage(
  object,
  img_name,
  img_dir,
  overwrite = FALSE,
  transform = FALSE,
  verbose = NULL
)

## S4 method for signature 'SpatialData'
writeImage(
  object,
  img_name,
  img_dir,
  overwrite = FALSE,
  transform = FALSE,
  verbose = TRUE
)

## S4 method for signature 'HistoImage'
writeImage(
  object,
  img_dir,
  overwrite = FALSE,
  transform = FALSE,
  verbose = TRUE
)

Arguments

object	An object of class SPATA2 or, in case of S4 generics, objects of classes for which a method has been defined.
...	Additional arguments passed to EBImage::writeImage.
img_name	A character string specifying the name of the image.
img_dir	A character string specifying the directory where the image should be saved. If NULL, the image is written to the current image directory as obtained by getImageDir().
overwrite	Logical. If TRUE, existing files with the same name in the specified directory will be overwritten.
transform	Logical value. If TRUE, image transformations defined during alignImage() and/or alignImageInteractive() are applied before saving the image. Defaults to FALSE. Only set to TRUE if you do not reassign the object after the function call. If transform is TRUE and you reassign the object, the transformed image will be saved, but the object itself will not reflect these changes (e.g., the transformation will not be undone in the object). This can lead to discrepancies between the saved image and the object’s internal state.
verbose	Logical. If TRUE, informative messages regarding the computational progress will be printed. (Warning messages will always be printed.)

Details

The writeImage() function writes the image associated with the specified img_name to the given directory img_dir.

Setting resize_fct to NULL:

After the image is written to the specified directory, the resize_fct transformation is set to NULL. This is to prevent an ever-decreasing reduction in image size since the factor is typically applied when the image is loaded into the object. If this factor is not reset after writing the image, subsequent loading and writing cycles would continually reduce the image size.

Differences in Assigning the Object:

The difference between using object <- writeImage(object) and simply calling writeImage(object) lies in the handling of the img_dir slot in the HistoImage class:

• object <- writeImage(object, ...): When you assign the result of the writeImage call back to the object, the function updates the dir slot with the directory path img_dir where the image was written. This ensures that the object now knows the location of its saved image, which can be useful for tracking and future references.

• writeImage(object, ...) without assignment: If you do not reassign the object, the image is still written to the specified directory, but the dir slot within the HistoImage object is not updated - because the updates were not reassigned.

Value

As pointed out in details, this function can be used to just write an image to disk while simultaneously storing the results in the respective object. After the image is successfully written to disk, the respective object, updated in terms of image directory and resize factor, is returned invisibly. See examples.

Examples

library(SPATA2)
library(SPATAData)

object <- downloadSpataObject("UKF313T")

# contains two images
getImageNames(object)

img_name <- "hires"
img_dir <- "my/new/image_directory.png"

# Example 1: Basic usage, save the image and update the object
object <- writeImage(object, img_name = img_name, img_dir = img_dir, overwrite = TRUE)
# The object now knows the location of the saved image.

# Example 2: Save the image without updating the object
writeImage(object, img_name = img_name, img_dir = img_dir, overwrite = TRUE)
# The image is saved, but the object does not update its internal directory reference.

# Example 3: Apply transformations before saving (but do not reassign the object)
writeImage(object, img_name = img_name, img_dir = img_dir, overwrite = TRUE, transform = TRUE)
# The image is saved with the transformations applied, but since we did not reassign,
# the object does not reflect these transformations internally.

# Example 4: Apply transformations and update the object
object <- writeImage(object, img_name = img_name, img_dir = img_dir, overwrite = TRUE, transform = TRUE)
# The image is saved with transformations applied, and the object is updated with the new directory and resize factor.

# Pitfall 1: Forgetting to reassign the object after writing with transformations
writeImage(object, img_name = img_name, img_dir = img_dir, overwrite = TRUE, transform = TRUE)
# If you now reload the object or access the image again, it may not reflect the transformations you just saved.

# Pitfall 2: Not setting overwrite = TRUE when a file already exists
# This will cause an error if a file with the same name already exists in the directory.
# writeImage(object, img_name = img_name, img_dir = img_dir)

theMILOlab/SPATA2 documentation built on Feb. 8, 2025, 11:41 p.m.