From a996f8c114c37936b1c46c3c9e22fd1b73758af2 Mon Sep 17 00:00:00 2001 From: HelenaLC Date: Fri, 21 Jun 2024 11:29:41 +0200 Subject: [PATCH] deprecate read10xVisium in favor of VisiumIO functions --- R/SpatialExperiment-colData.R | 2 +- R/SpatialExperiment-combine.R | 2 +- R/SpatialExperiment-methods.R | 2 +- R/SpatialExperiment-rotate-mirror.R | 2 +- R/SpatialExperiment.R | 22 +++++--- R/imgData-methods.R | 2 +- R/read10xVisium.R | 2 + R/show.R | 2 +- R/subset.R | 2 +- man/SpatialExperiment-colData.Rd | 4 +- man/SpatialExperiment-combine.Rd | 2 +- man/SpatialExperiment-methods.Rd | 12 ++-- man/SpatialExperiment-misc.Rd | 2 +- man/SpatialExperiment-rotate-mirror.Rd | 2 +- man/SpatialExperiment-subset.Rd | 2 +- man/SpatialExperiment.Rd | 22 +++++--- man/imgData-methods.Rd | 2 +- .../testthat/test_SpatialExperiment-assays.R | 2 +- tests/testthat/test_SpatialExperiment-cbind.R | 2 +- .../testthat/test_SpatialExperiment-colData.R | 2 +- .../testthat/test_SpatialExperiment-methods.R | 2 +- .../test_SpatialExperiment-rotate-mirror.R | 2 +- .../testthat/test_SpatialExperiment-subset.R | 2 +- tests/testthat/test_SpatialExperiment.R | 2 +- tests/testthat/test_imgData-methods.R | 2 +- vignettes/SpatialExperiment.Rmd | 55 ++++++++----------- 26 files changed, 80 insertions(+), 77 deletions(-) diff --git a/R/SpatialExperiment-colData.R b/R/SpatialExperiment-colData.R index e3d6227..2cfd177 100644 --- a/R/SpatialExperiment-colData.R +++ b/R/SpatialExperiment-colData.R @@ -24,7 +24,7 @@ #' @return a \code{\link{SpatialExperiment}} object with updated \code{colData} #' #' @examples -#' example(read10xVisium) +#' example("SpatialExperiment-methods") #' #' # empty replacement retains sample identifiers #' colData(spe) <- NULL diff --git a/R/SpatialExperiment-combine.R b/R/SpatialExperiment-combine.R index 7cd18b3..46cf418 100644 --- a/R/SpatialExperiment-combine.R +++ b/R/SpatialExperiment-combine.R @@ -45,7 +45,7 @@ #' Dario Righelli #' #' @examples -#' example(read10xVisium, echo = FALSE) +#' example(SpatialExperiment) #' #' # merging with duplicated 'sample_id's #' # will automatically assign unique identifiers diff --git a/R/SpatialExperiment-methods.R b/R/SpatialExperiment-methods.R index 3091c3f..a47d3ac 100644 --- a/R/SpatialExperiment-methods.R +++ b/R/SpatialExperiment-methods.R @@ -89,7 +89,7 @@ #' @return Return value varies depending on method, as described below. #' #' @examples -#' example(read10xVisium) +#' example(SpatialExperiment) #' #' # spatialCoords returns a numeric matrix #' head(spatialCoords(spe)) diff --git a/R/SpatialExperiment-rotate-mirror.R b/R/SpatialExperiment-rotate-mirror.R index 980255c..fe57189 100644 --- a/R/SpatialExperiment-rotate-mirror.R +++ b/R/SpatialExperiment-rotate-mirror.R @@ -65,7 +65,7 @@ #' @author Nicholas J. Eagles #' #' @examples -#' example(read10xVisium) +#' example(SpatialExperiment) #' #' # rotateCoords(), mirrorCoords(), rotateObject(), and mirrorObject() return a #' # SpatialExperiment, potentially subsetted by sample. diff --git a/R/SpatialExperiment.R b/R/SpatialExperiment.R index 9039d02..6b516c1 100644 --- a/R/SpatialExperiment.R +++ b/R/SpatialExperiment.R @@ -85,9 +85,9 @@ #' To combine multiple samples within a single object, see #' \code{\link{combine}}. #' -#' For 10x Genomics Visium datasets, the function \code{\link{read10xVisium}} -#' can be used to load data and create a \code{SpatialExperiment} object -#' directly from Space Ranger output files. +#' For 10x Genomics Visium datasets, the \code{\link[VisiumIO]{TENxVisiumList}} +#' and \code{\link[VisiumIO]{import}} functions can be used to load data into +#' a \code{SpatialExperiment} object directly from Space Ranger output files. #' #' @seealso #' \code{?"\link{SpatialExperiment-methods}"}, which includes: @@ -111,8 +111,6 @@ #' #' \code{\link{SpatialImage}} #' -#' \code{\link{read10xVisium}} -#' #' @author Dario Righelli and Helena L. Crowell #' #' @return A \code{SpatialExperiment} object. @@ -156,11 +154,19 @@ #' sample_id = "foo")) #' #' ############################################################# -#' # Example 2: Spot-based ST (10x Visium) using 'read10xVisium' +#' # Example 2: Spot-based ST (10x Visium) using 'VisiumIO' #' ############################################################# #' -#' # see ?read10xVisium for details -#' example(read10xVisium) +#' library(VisiumIO) +#' dir <- list.dirs(system.file( +#' file.path("extdata", "10xVisium"), +#' package = "SpatialExperiment"), +#' recursive = FALSE, full.names = TRUE) +#' (spe <- import(TENxVisiumList( +#' sampleFolders = dir, +#' sample_ids = basename(dir), +#' processing = "raw", +#' images = "lowres"))) #' #' ############################## #' # Example 3: Molecule-based ST diff --git a/R/imgData-methods.R b/R/imgData-methods.R index d3d4603..3a75045 100644 --- a/R/imgData-methods.R +++ b/R/imgData-methods.R @@ -66,7 +66,7 @@ #' with modified a \code{raster} matrix. #' #' @examples -#' example(read10xVisium) +#' example(SpatialExperiment) #' #' # 'SpatialImage' accession #' (spi <- getImg(spe)) diff --git a/R/read10xVisium.R b/R/read10xVisium.R index 0ef83d2..e6319b0 100644 --- a/R/read10xVisium.R +++ b/R/read10xVisium.R @@ -92,6 +92,8 @@ read10xVisium <- function(samples="", images="lowres", load=TRUE) { + .Deprecated("VisiumIO::TENxVisium(List)") + # check if DropletUtils is installed if (!requireNamespace("DropletUtils", quietly = TRUE)) { warning("DropletUtils package must be installed to use read10xVisium()") diff --git a/R/show.R b/R/show.R index fa3819e..ef72223 100644 --- a/R/show.R +++ b/R/show.R @@ -14,7 +14,7 @@ #' @author Dario Righelli and Helena L. Crowell #' #' @examples -#' example(read10xVisium) +#' example(SpatialExperiment) #' spe NULL diff --git a/R/subset.R b/R/subset.R index 4e7dacc..fac9198 100644 --- a/R/subset.R +++ b/R/subset.R @@ -22,7 +22,7 @@ #' @return a \code{\link{SpatialExperiment}} object #' #' @examples -#' example(read10xVisium) +#' example(SpatialExperiment) #' #' dim(spe) #' diff --git a/man/SpatialExperiment-colData.Rd b/man/SpatialExperiment-colData.Rd index b35c486..95f4b28 100644 --- a/man/SpatialExperiment-colData.Rd +++ b/man/SpatialExperiment-colData.Rd @@ -10,7 +10,7 @@ \usage{ \S4method{colData}{SpatialExperiment,DataFrame}(x) <- value -\S4method{colData}{SpatialExperiment,`NULL`}(x) <- value +\S4method{colData}{SpatialExperiment,NULL}(x) <- value } \arguments{ \item{x}{a \code{\link{SpatialExperiment}}} @@ -35,7 +35,7 @@ retained. In addition, checks are performed against the \code{sample_id}s in \code{\link{imgData}}. } \examples{ -example(read10xVisium) +example("SpatialExperiment-methods") # empty replacement retains sample identifiers colData(spe) <- NULL diff --git a/man/SpatialExperiment-combine.Rd b/man/SpatialExperiment-combine.Rd index 976ea05..fa26d9f 100644 --- a/man/SpatialExperiment-combine.Rd +++ b/man/SpatialExperiment-combine.Rd @@ -51,7 +51,7 @@ Refer to \code{?\link[base]{cbind}} for the interpretation of } \examples{ -example(read10xVisium, echo = FALSE) +example(SpatialExperiment) # merging with duplicated 'sample_id's # will automatically assign unique identifiers diff --git a/man/SpatialExperiment-methods.Rd b/man/SpatialExperiment-methods.Rd index 965e3f9..8fbf6e6 100644 --- a/man/SpatialExperiment-methods.Rd +++ b/man/SpatialExperiment-methods.Rd @@ -36,25 +36,25 @@ \S4method{spatialData}{SpatialExperiment,DFrame}(x) <- value -\S4method{spatialData}{SpatialExperiment,`NULL`}(x) <- value +\S4method{spatialData}{SpatialExperiment,NULL}(x) <- value \S4method{spatialDataNames}{SpatialExperiment}(x) \S4method{spatialDataNames}{SpatialExperiment,character}(x) <- value -\S4method{spatialDataNames}{SpatialExperiment,`NULL`}(x) <- value +\S4method{spatialDataNames}{SpatialExperiment,NULL}(x) <- value \S4method{spatialCoords}{SpatialExperiment}(x) \S4method{spatialCoords}{SpatialExperiment,matrix}(x) <- value -\S4method{spatialCoords}{SpatialExperiment,`NULL`}(x) <- value +\S4method{spatialCoords}{SpatialExperiment,NULL}(x) <- value \S4method{spatialCoordsNames}{SpatialExperiment}(x) \S4method{spatialCoordsNames}{SpatialExperiment,character}(x) <- value -\S4method{spatialCoordsNames}{SpatialExperiment,`NULL`}(x) <- value +\S4method{spatialCoordsNames}{SpatialExperiment,NULL}(x) <- value \S4method{scaleFactors}{SpatialExperiment}(x, sample_id = TRUE, image_id = TRUE) @@ -64,7 +64,7 @@ \S4method{imgData}{SpatialExperiment,DataFrame}(x) <- value -\S4method{imgData}{SpatialExperiment,`NULL`}(x) <- value +\S4method{imgData}{SpatialExperiment,NULL}(x) <- value } \arguments{ \item{x}{A \code{\link{SpatialExperiment}} object.} @@ -159,7 +159,7 @@ methods to rotate and mirror SpatialExperiment objects and their } \examples{ -example(read10xVisium) +example(SpatialExperiment) # spatialCoords returns a numeric matrix head(spatialCoords(spe)) diff --git a/man/SpatialExperiment-misc.Rd b/man/SpatialExperiment-misc.Rd index d1db62f..17722e8 100644 --- a/man/SpatialExperiment-misc.Rd +++ b/man/SpatialExperiment-misc.Rd @@ -19,7 +19,7 @@ descendants that do not fit into any other documentation category such as, for example, show methods. } \examples{ -example(read10xVisium) +example(SpatialExperiment) spe } \author{ diff --git a/man/SpatialExperiment-rotate-mirror.Rd b/man/SpatialExperiment-rotate-mirror.Rd index 13f0c71..487aab9 100644 --- a/man/SpatialExperiment-rotate-mirror.Rd +++ b/man/SpatialExperiment-rotate-mirror.Rd @@ -90,7 +90,7 @@ Additional details for each type of data attribute are provided below. } \examples{ -example(read10xVisium) +example(SpatialExperiment) # rotateCoords(), mirrorCoords(), rotateObject(), and mirrorObject() return a # SpatialExperiment, potentially subsetted by sample. diff --git a/man/SpatialExperiment-subset.Rd b/man/SpatialExperiment-subset.Rd index d12796e..0d9afc6 100644 --- a/man/SpatialExperiment-subset.Rd +++ b/man/SpatialExperiment-subset.Rd @@ -28,7 +28,7 @@ the remainder of the object. } \examples{ -example(read10xVisium) +example(SpatialExperiment) dim(spe) diff --git a/man/SpatialExperiment.Rd b/man/SpatialExperiment.Rd index 5348448..e995b0d 100644 --- a/man/SpatialExperiment.Rd +++ b/man/SpatialExperiment.Rd @@ -98,9 +98,9 @@ this will be assumed from \code{sample_id} and \code{imageSources} instead. To combine multiple samples within a single object, see \code{\link{combine}}. -For 10x Genomics Visium datasets, the function \code{\link{read10xVisium}} -can be used to load data and create a \code{SpatialExperiment} object -directly from Space Ranger output files. +For 10x Genomics Visium datasets, the \code{\link[VisiumIO]{TENxVisiumList}} +and \code{\link[VisiumIO]{import}} functions can be used to load data into +a \code{SpatialExperiment} object directly from Space Ranger output files. } \examples{ ######################################################### @@ -141,11 +141,19 @@ rd <- S4Vectors::DataFrame( sample_id = "foo")) ############################################################# -# Example 2: Spot-based ST (10x Visium) using 'read10xVisium' +# Example 2: Spot-based ST (10x Visium) using 'VisiumIO' ############################################################# -# see ?read10xVisium for details -example(read10xVisium) +library(VisiumIO) +dir <- list.dirs(system.file( + file.path("extdata", "10xVisium"), + package = "SpatialExperiment"), + recursive = FALSE, full.names = TRUE) +(spe <- import(TENxVisiumList( + sampleFolders = dir, + sample_ids = basename(dir), + processing = "raw", + images = "lowres"))) ############################## # Example 3: Molecule-based ST @@ -205,8 +213,6 @@ y <- as.matrix(unclass(y)) \code{?"\link{imgData-methods}"} \code{\link{SpatialImage}} - -\code{\link{read10xVisium}} } \author{ Dario Righelli and Helena L. Crowell diff --git a/man/imgData-methods.Rd b/man/imgData-methods.Rd index 46cd8d4..81cb360 100644 --- a/man/imgData-methods.Rd +++ b/man/imgData-methods.Rd @@ -90,7 +90,7 @@ the image-related data stored inside a \code{SpatialExperiment}'s } } \examples{ -example(read10xVisium) +example(SpatialExperiment) # 'SpatialImage' accession (spi <- getImg(spe)) diff --git a/tests/testthat/test_SpatialExperiment-assays.R b/tests/testthat/test_SpatialExperiment-assays.R index 3a964ad..248783b 100644 --- a/tests/testthat/test_SpatialExperiment-assays.R +++ b/tests/testthat/test_SpatialExperiment-assays.R @@ -1,4 +1,4 @@ -example(read10xVisium, echo = FALSE) +example(SpatialExperiment, echo = FALSE) test_that("molecules()/<- gets/sets assay(., 'molecules')", { tmp <- spe diff --git a/tests/testthat/test_SpatialExperiment-cbind.R b/tests/testthat/test_SpatialExperiment-cbind.R index 5100a6c..9aea348 100644 --- a/tests/testthat/test_SpatialExperiment-cbind.R +++ b/tests/testthat/test_SpatialExperiment-cbind.R @@ -1,4 +1,4 @@ -example(read10xVisium, echo = FALSE) +example(SpatialExperiment, echo = FALSE) test_that("duplicated sample_ids are made unique with a message", { expect_message(new <- cbind(spe, spe)) diff --git a/tests/testthat/test_SpatialExperiment-colData.R b/tests/testthat/test_SpatialExperiment-colData.R index aa577fd..2a83845 100644 --- a/tests/testthat/test_SpatialExperiment-colData.R +++ b/tests/testthat/test_SpatialExperiment-colData.R @@ -1,4 +1,4 @@ -example(read10xVisium, echo = FALSE) +example(SpatialExperiment, echo = FALSE) test_that("colData()<-NULL retains only sample_id", { tmp <- spe diff --git a/tests/testthat/test_SpatialExperiment-methods.R b/tests/testthat/test_SpatialExperiment-methods.R index ffe1b46..3345b6c 100644 --- a/tests/testthat/test_SpatialExperiment-methods.R +++ b/tests/testthat/test_SpatialExperiment-methods.R @@ -1,4 +1,4 @@ -example(read10xVisium, echo = FALSE) +example(SpatialExperiment, echo = FALSE) test_that("spatialData()", { spd <- spatialData(spe) diff --git a/tests/testthat/test_SpatialExperiment-rotate-mirror.R b/tests/testthat/test_SpatialExperiment-rotate-mirror.R index a7bb6eb..61843c0 100644 --- a/tests/testthat/test_SpatialExperiment-rotate-mirror.R +++ b/tests/testthat/test_SpatialExperiment-rotate-mirror.R @@ -1,4 +1,4 @@ -example(read10xVisium, echo = FALSE) +example(SpatialExperiment, echo = FALSE) test_that("rotateCoords, non-null sample_id", { # Subset followed by identity rotation should be equivalent to simply diff --git a/tests/testthat/test_SpatialExperiment-subset.R b/tests/testthat/test_SpatialExperiment-subset.R index 42e365b..b43dcb0 100644 --- a/tests/testthat/test_SpatialExperiment-subset.R +++ b/tests/testthat/test_SpatialExperiment-subset.R @@ -1,4 +1,4 @@ -example(read10xVisium, echo = FALSE) +example(SpatialExperiment, echo = FALSE) test_that("missing i/j retains all", { expect_identical(spe, spe[, ]) diff --git a/tests/testthat/test_SpatialExperiment.R b/tests/testthat/test_SpatialExperiment.R index b1554fc..8a34624 100644 --- a/tests/testthat/test_SpatialExperiment.R +++ b/tests/testthat/test_SpatialExperiment.R @@ -1,4 +1,4 @@ -example(read10xVisium, echo = FALSE) +example(SpatialExperiment, echo = FALSE) test_that("empty constructor", { spe <- SpatialExperiment() diff --git a/tests/testthat/test_imgData-methods.R b/tests/testthat/test_imgData-methods.R index 318841d..0660356 100644 --- a/tests/testthat/test_imgData-methods.R +++ b/tests/testthat/test_imgData-methods.R @@ -1,4 +1,4 @@ -example(read10xVisium, echo = FALSE) +example(SpatialExperiment, echo = FALSE) test_that("getImg/imgRaster/Source w/o imgData return NULL", { x <- spe diff --git a/vignettes/SpatialExperiment.Rmd b/vignettes/SpatialExperiment.Rmd index 94eaf34..98be8c8 100644 --- a/vignettes/SpatialExperiment.Rmd +++ b/vignettes/SpatialExperiment.Rmd @@ -62,11 +62,10 @@ For demonstration of the general class structure, we load an example ```{r message = FALSE} library(SpatialExperiment) -example(read10xVisium, echo = FALSE) +example(SpatialExperiment, echo = FALSE) spe ``` - ## `spatialCoords` In addition to observation metadata stored inside the `colData` slot, @@ -323,15 +322,16 @@ rd <- S4Vectors::DataFrame( sample_id = "foo")) ``` -Alternatively, the `read10xVisium()` function facilitates the import of -*10x Genomics Visium* data to handle one or more samples organized in -folders reflecting the default *Space Ranger* folder tree organization, -as illustrated below (where "raw/filtered" refers to either "raw" or -"filtered" to match the `data` argument). Note that the base directory -"outs/" from Space Ranger can either be included manually in the paths -provided in the `samples` argument, or can be ignored; if ignored, it will -be added automatically. The `.h5` files are used if `type = "HDF5"`. (Note -that `tissue_positions.csv` was renamed in Space Ranger v2.0.0.) +Alternatively, `r BiocStyle::Biocpkg("VisiumIO")`'s `TENxVisium/List()` +functions facilitate the import of *10x Genomics Visium* data to handle one +or more samples organized in folders reflecting the default *Space Ranger* +folder tree organization, as illustrated below (where "raw/filtered" refers +to either "raw" or "filtered" to match the `data` argument). Note that the +base directory "outs/" from Space Ranger can either be included manually in the +paths provided in the `sampleFolders` argument, or can be ignored; if ignored, +it will be added automatically. (Note that `tissue_positions.csv` was renamed +in Space Ranger v2.0.0; the `tissuePattern` argument can be used to specify a +pattern to match the tissue positions file.) ```{bash, eval = FALSE} sample @@ -347,32 +347,21 @@ sample · · · | — tissue_positions.csv ``` -Using `read10xVisium()`, the above code to construct the same SPE is reduced to: - -```{r} -dir <- system.file( - file.path("extdata", "10xVisium"), - package = "SpatialExperiment") - -sample_ids <- c("section1", "section2") -samples <- file.path(dir, sample_ids, "outs") - -(spe10x <- read10xVisium(samples, sample_ids, - type = "sparse", data = "raw", - images = "lowres", load = FALSE)) -``` - -Or alternatively, omitting the base directory `outs/` from Space Ranger: +Using `TENxVisiumList()`, the above code to construct the same SPE is reduced to: ```{r} -samples2 <- file.path(dir, sample_ids) - -(spe10x2 <- read10xVisium(samples2, sample_ids, - type = "sparse", data = "raw", - images = "lowres", load = FALSE)) +library(VisiumIO) +dir <- list.dirs(system.file( + file.path("extdata", "10xVisium"), + package = "SpatialExperiment"), + recursive = FALSE, full.names = TRUE) +(ids <- basename(dir)) +(vl <- TENxVisiumList( + sampleFolders = dir, sample_ids = ids, + processing = "raw", image = "lowres")) +(spe10x <- import(vl)) ``` - ## Molecule-based To demonstrate how to accommodate molecule-based ST data