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

Defaults to the output of fetch_data(type = 'spe'). This is a SpatialExperiment-class object with the spot-level Visium data and information required for visualizing the histology. See fetch_data() for more details.

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")
    ))
}
#> 2024-04-19 19:41:22.67984 loading file /github/home/.cache/R/BiocFileCache/c9922e59250_Human_DLPFC_Visium_processedData_sce_scran_spatialLIBD.Rdata%3Fdl%3D1
#> 2024-04-19 19:41:38.403594 adding image for sample 151507
#> 2024-04-19 19:41:39.197714 adding image for sample 151508
#> Warning: No image was found for sample: 151508
#> 2024-04-19 19:41:39.198045 adding image for sample 151509
#> Warning: No image was found for sample: 151509
#> 2024-04-19 19:41:39.198256 adding image for sample 151510
#> Warning: No image was found for sample: 151510
#> 2024-04-19 19:41:39.198484 adding image for sample 151669
#> Warning: No image was found for sample: 151669
#> 2024-04-19 19:41:39.198704 adding image for sample 151670
#> Warning: No image was found for sample: 151670
#> 2024-04-19 19:41:39.198904 adding image for sample 151671
#> Warning: No image was found for sample: 151671
#> 2024-04-19 19:41:39.199095 adding image for sample 151672
#> Warning: No image was found for sample: 151672
#> 2024-04-19 19:41:39.199286 adding image for sample 151673
#> Warning: No image was found for sample: 151673
#> 2024-04-19 19:41:39.199477 adding image for sample 151674
#> Warning: No image was found for sample: 151674
#> 2024-04-19 19:41:39.199686 adding image for sample 151675
#> Warning: No image was found for sample: 151675
#> 2024-04-19 19:41:39.199876 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