Add non-standard images with the same dimensions as current ones

This function re-uses the SpatialExperiment::scaleFactors() from current images when adding new images. This is useful if you take for example a multi-channel VisiumIF image and break into several single-channel images that all have the same dimensions. So you could have a set of images such as channel_01_lowres and channel_02_lowres that have the same dimensions and viewing area as the lowres image produced by SpaceRanger, each with only one channel. Similarly, you might have done some image manipulation for a given image and generated one or more images with the same dimensions as existing images.

add_images(
  spe,
  image_dir,
  image_pattern,
  image_id_current = "lowres",
  image_id = image_pattern,
  image_paths = locate_images(spe, image_dir, image_pattern)
)

Arguments

spe

A SpatialExperiment-class object. See fetch_data() for how to download some example objects or read10xVisiumWrapper() to read in spaceranger --count output files and build your own spe object.

image_dir

A character(1) specifying a path to a directory containing image files with the pattern sampleID_pattern.png.

image_pattern

A character(1) specifying the pattern for the image files.

image_id_current

A character(1) specifying the name of the current existing image in spe that has the same scaling factor that to be used with the additional images.

image_id

A character(1) specifying the name to use in the new images. It cannot be the same as one used for existing images in spe for a given sample. It equals image_pattern by default.

image_paths

A named character() vector with the paths to the images. The names have to match the spe$sample_id and cannot be repeated. By default locate_images() is used but you can alternatively specify image_paths and ignore image_dir and image_pattern.

Value

A SpatialExperiment-class object with the additional image data in imgData(spe).

See also

Other Functions for adding non-standard images: locate_images()

Examples

if (enough_ram()) {
    ## Obtain the necessary data
    if (!exists("spe")) spe <- fetch_data("spe")

    ## Add an image
    SpatialExperiment::imgData(add_images(
        spe,
        image_id_current = "lowres",
        image_id = "lowres_aws",
        image_paths = c("151507" = "https://spatial-dlpfc.s3.us-east-2.amazonaws.com/images/151507_tissue_lowres_image.png")
    ))
}
#> 2025-09-17 01:16:34.334033 loading file /github/home/.cache/R/BiocFileCache/22ac1bc3fd2d_Human_DLPFC_Visium_processedData_sce_scran_spatialLIBD.Rdata%3Fdl%3D1
#> 2025-09-17 01:16:46.056657 adding image for sample 151507
#> 2025-09-17 01:16:46.734566 adding image for sample 151508
#> Warning: No image was found for sample: 151508
#> 2025-09-17 01:16:46.735386 adding image for sample 151509
#> Warning: No image was found for sample: 151509
#> 2025-09-17 01:16:46.735926 adding image for sample 151510
#> Warning: No image was found for sample: 151510
#> 2025-09-17 01:16:46.73645 adding image for sample 151669
#> Warning: No image was found for sample: 151669
#> 2025-09-17 01:16:46.736955 adding image for sample 151670
#> Warning: No image was found for sample: 151670
#> 2025-09-17 01:16:46.737469 adding image for sample 151671
#> Warning: No image was found for sample: 151671
#> 2025-09-17 01:16:46.737972 adding image for sample 151672
#> Warning: No image was found for sample: 151672
#> 2025-09-17 01:16:46.738473 adding image for sample 151673
#> Warning: No image was found for sample: 151673
#> 2025-09-17 01:16:46.738964 adding image for sample 151674
#> Warning: No image was found for sample: 151674
#> 2025-09-17 01:16:46.739465 adding image for sample 151675
#> Warning: No image was found for sample: 151675
#> 2025-09-17 01:16:46.739943 adding image for sample 151676
#> Warning: No image was found for sample: 151676
#> DataFrame with 13 rows and 4 columns
#>       sample_id    image_id   data scaleFactor
#>     <character> <character> <list>   <numeric>
#> 1        151507      lowres   ####   0.0450045
#> 2        151508      lowres   ####   0.0450045
#> 3        151509      lowres   ####   0.0450045
#> 4        151510      lowres   ####   0.0450045
#> 5        151669      lowres   ####   0.0450045
#> ...         ...         ...    ...         ...
#> 9        151673      lowres   ####   0.0450045
#> 10       151674      lowres   ####   0.0450045
#> 11       151675      lowres   ####   0.0450045
#> 12       151676      lowres   ####   0.0450045
#> 13       151507  lowres_aws   ####   0.0450045