Merge pull request #9556 from satijalab/feat/visiumv1-return

Feat/VisiumV1 return

Author: dcollins15

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: Seurat
-Version: 5.1.0.9016
+Version: 5.1.0.9017
 Title: Tools for Single Cell Genomics
 Description: A toolkit for quality control, analysis, and exploration of single cell RNA sequencing data. 'Seurat' aims to enable users to identify and interpret sources of heterogeneity from single cell transcriptomic measurements, and to integrate diverse types of single cell data. See Satija R, Farrell J, Gennert D, et al (2015) <doi:10.1038/nbt.3192>, Macosko E, Basu A, Satija R, et al (2015) <doi:10.1016/j.cell.2015.05.002>, Stuart T, Butler A, et al (2019) <doi:10.1016/j.cell.2019.05.031>, and Hao, Hao, et al (2020) <doi:10.1101/2020.10.12.335331> for more details.
 Authors@R: c(
@@ -68,7 +68,6 @@ Imports:
     plotly (>= 4.9.0),
     png,
     progressr,
-    purrr,
     RANN,
     RColorBrewer,
     Rcpp (>= 1.0.7),

NAMESPACE

@@ -49,6 +49,7 @@ S3method(GetAssay,Seurat)
 S3method(GetImage,STARmap)
 S3method(GetImage,SlideSeq)
 S3method(GetImage,VisiumV1)
+S3method(GetImage,VisiumV2)
 S3method(GetTissueCoordinates,STARmap)
 S3method(GetTissueCoordinates,SlideSeq)
 S3method(GetTissueCoordinates,VisiumV1)
@@ -796,7 +797,6 @@ importFrom(plotly,plot_ly)
 importFrom(plotly,raster2uri)
 importFrom(png,readPNG)
 importFrom(progressr,progressor)
-importFrom(purrr,imap)
 importFrom(reticulate,import)
 importFrom(reticulate,py_module_available)
 importFrom(reticulate,py_set_seed)

NEWS.md

@@ -1,6 +1,7 @@
 # Unreleased
 
 ## Changes
+- Added `image.type` parameter to `Read10X_Image` enabling `VisiumV1` instances to be populated instead of instances of the default `VisiumV2` class ([#9556](https://github.com/satijalab/seurat/pull/9556))
 - Fixed `IntegrateLayers` to respect the `dims.to.integrate` parameter.
 - Added `stroke.size` parameter to `DimPlot` ([#8180](https://github.com/satijalab/seurat/pull/8180))
 - Updated `RunLeiden` to use the `leidenbase` package instead of `leiden`; deprecated the `method` parameter for `RunLeiden` and `FindClusters`; updated `RunLeiden` to reset `random.seed` to 1 if the value is 0 or less ([#6792](https://github.com/satijalab/seurat/pull/6792))

R/objects.R

@@ -1630,6 +1630,14 @@ GetImage.VisiumV1 <- function(
   return(image)
 }
 
+
+#'
+#' @rdname GetImage
+#' @concept objects
+#' @concept spatial
+#' @method GetImage VisiumV2
+#' @export
+#'
 GetImage.VisiumV2 <- GetImage.VisiumV1
 
 #' Get Tissue Coordinates

R/preprocessing.R

@@ -510,9 +510,7 @@ GetResidual <- function(
 #' @return A \code{Seurat} object
 #'
 #' @importFrom png readPNG
-#' @importFrom grid rasterGrob
 #' @importFrom jsonlite fromJSON
-#' @importFrom purrr imap
 #'
 #' @export
 #' @concept preprocessing
@@ -1213,6 +1211,7 @@ Read10X_h5 <- function(filename, use.names = TRUE, unique.features = TRUE) {
 #' @param slice Name for the image, used to populate the instance's key
 #' @param filter.matrix Filter spot/feature matrix to only include spots that
 #' have been determined to be over tissue
+#' @param image.type Image type to return, one of: "VisiumV1" or "VisiumV2"
 #'
 #' @return A \code{\link{VisiumV2}} object
 #'
@@ -1226,37 +1225,68 @@ Read10X_Image <- function(
   image.name = "tissue_lowres_image.png",
   assay = "Spatial",
   slice = "slice1",
-  filter.matrix = TRUE
+  filter.matrix = TRUE,
+  image.type = "VisiumV2"
 ) {
+  # Validate the `image.type` parameter.
+  image.type <- match.arg(image.type, choices = c("VisiumV1", "VisiumV2"))
+
+  # Read in the H&E stain image.
   image <- png::readPNG(
     source = file.path(
       image.dir,
       image.name
     )
   )
 
-  # read in the scale factors
+  # Read in the scale factors.
   scale.factors <- Read10X_ScaleFactors(
     filename = file.path(image.dir, "scalefactors_json.json")
   )
 
-  # read in the tissue coordinates as a data.frame
+  # Read in the tissue coordinates as a data.frame.
   coordinates <- Read10X_Coordinates(
     filename = Sys.glob(file.path(image.dir, "*tissue_positions*")),
     filter.matrix
   )
-  # create an `sp` compatible `FOV` instance
+
+  # Use the `slice` value to populate a Seurat-style identifier for the image.
+  key <- Key(slice, quiet = TRUE)
+
+  # Return the specified `image.type`.
+  if (image.type == "VisiumV1") {
+    visium.v1 <- new(
+      Class = image.type,
+      assay = assay,
+      key = key,
+      coordinates = coordinates,
+      scale.factors = scale.factors,
+      image = image
+    )
+
+    # As of v5.1.0 `Radius.VisiumV1` no longer returns the value of the 
+    # `spot.radius` slot and instead calculates the value on the fly, but we 
+    # can populate the static slot in case it's depended on.
+    visium.v1@spot.radius <- Radius(visium.v1)
+
+    return(visium.v1)
+  }
+
+  # If `image.type` is not "VisiumV1" then it must be "VisiumV2".
+  stopifnot(image.type == "VisiumV2")
+
+  # Create an `sp` compatible `FOV` instance.
   fov <- CreateFOV(
     coordinates[, c("imagerow", "imagecol")],
     type = "centroids",
     radius = scale.factors[["spot"]],
     assay = assay,
-    key = Key(slice, quiet = TRUE)
+    key = key
   )
 
-  # build the final `VisiumV2` - essentially just adding `image` and
-  # `scale.factors` to the object
-  visium.fov <- new(
+  # Build the final `VisiumV2` instance, essentially just adding `image` and
+  # `scale.factors` to the `fov`.
+  visium.v2 <- new(
     Class = "VisiumV2",
     boundaries = fov@boundaries,
     molecules = fov@molecules,
@@ -1266,7 +1296,7 @@ Read10X_Image <- function(
     scale.factors = scale.factors
   )
 
-  return(visium.fov)
+  return(visium.v2)
 }
 
 #' Load 10X Genomics Visium Tissue Positions

man/GetImage.Rd

@@ -132,6 +132,31 @@ test_that("Read10X_Image works as expected", {
     )
     # the size of the two images should be different
     expect_false(all(dim(image.hires) == dim(image.lowres)))
+
+    # `VisiumV1` image
+    image.v1 <- Read10X_Image(
+      path.to.image,
+      image.name = "tissue_lowres_image.png",
+      image.type = "VisiumV1"
+    )
+    coordinates <- GetTissueCoordinates(image.v1, scale = "lowres")
+    spot.radius <- Radius(image.v1, scale = "lowres")
+    scale.factors <- ScaleFactors(image.v1)
+    # check that the scale factors were read in as expected
+    expect_true(identical(scale.factors, scale.factors.expected))
+    # check that `coordinates` contains values scaled for the low resolution PNG
+    # also make sure that it has the expected column names
+    coordinates.expected.v1 <- coordinates.expected
+    colnames(coordinates.expected.v1) <- c("imagerow", "imagecol")
+    expect_equal(
+      coordinates[, c("imagerow", "imagecol")] / scale.factors[["lowres"]],
+      coordinates.expected.v1
+    )
+    # check that the spot size is similarly scaled
+    expect_equal(
+      (spot.radius / scale.factors[["lowres"]] * max(dim(image.lowres))),
+      scale.factors.expected[["spot"]],
+    )
   }
 })