SpatialExperiment coercion methods — SpatialExperiment-coercion • SpatialExperiment

The SpatialExperiment class inherits from the SingleCellExperiment class making it necessary to coerce between these classes. To do so, we designed two different methods: the traditional as method and the toSpatialExperiment function (recommended). The as method checks if the SingleCellExperiment object has already populated int_colData with three elements: spatialData, spatialCoords, and imgData. It also checks if colData already contains a sample_id. In case these checks pass the new SpatialExperiment will have the same values as the SingleCellExperiment passed object. Otherwise a SpatialExperiment with default values for these slots will be created.

The toSpatialExperiment method expects a SingleCellExperiment object and additional arguments as explained in the related section of this documentation. In case the SingleCellExperiment object has already populated int_colData with spatialData and/or spatialCoords and/or imgData, these will be respectively overwritten in case the arguments spatialData/spatialDataNames and/or spatialCoords/spatialCoordsNames and/or imgData are not NULL.

Arguments

sce: A SingleCellExperiment object.
sample_id: A character sample identifier, which matches the sample_id in imgData. The sample_id will also be stored in a new column in colData, if not already present. Default = sample01.
spatialCoordsNames: A character vector of column names from colData containing spatial coordinates, which will be accessible with spatialCoords. Alternatively, the spatialCoords argument may be provided. If both are provided, spatialCoordsNames is given precedence, and a warning is returned. Default = c("x", "y").
spatialCoords: A numeric matrix containing columns of spatial coordinates, which will be accessible with spatialCoords. Alternatively, spatialCoordsNames may be provided. If both are provided, spatialCoordsNames is given precedence, and a warning is returned.
scaleFactors: Optional scale factors associated with the image(s). This can be provided as a numeric value, numeric vector, list, or file path to a JSON file for the 10x Genomics Visium platform. For 10x Genomics Visium, the correct scale factor will automatically be selected depending on the resolution of the image from imageSources. Default = 1.
imgData: Optional DataFrame containing the image data. Alternatively, this can be built from the arguments imageSources and image_id (see Details).
imageSources: Optional file path(s) or URL(s) for one or more image sources.
image_id: Optional character vector (same length as imageSources) containing unique image identifiers.
loadImage: Logical indicating whether to load image into memory. Default = FALSE.
spatialDataNames: (Deprecated) A character vector of column names from colData to include in spatialData. Alternatively, the spatialData argument may be provided. If both are provided, spatialDataNames is given precedence, and a warning is returned. (Note: spatialData and spatialDataNames have been deprecated; colData and spatialCoords should be used for all columns. The arguments have been retained for backward compatibility but may be removed in the future.)
spatialData: (Deprecated) A DataFrame containing columns to store in spatialData, which must contain at least the columns of spatial coordinates. Alternatively, spatialDataNames may be provided. If both are provided, spatialDataNames is given precedence, and a warning is returned. (Note: spatialData and spatialDataNames have been deprecated; colData and spatialCoords should be used for all columns. The arguments have been retained for backward compatibility but may be removed in the future.)

Examples

dir <- system.file(
    file.path("extdata", "10xVisium", "section1", "outs"),
    package = "SpatialExperiment")

# read in counts
fnm <- file.path(dir, "raw_feature_bc_matrix")
sce <- DropletUtils::read10xCounts(fnm)

# read in spatial coordinates
fnm <- file.path(dir, "spatial", "tissue_positions_list.csv")
xyz <- read.csv(fnm, header = FALSE,
    col.names = c("barcode", "in_tissue", "array_row", "array_col",
    "pxl_row_in_fullres", "pxl_col_in_fullres"))

# read in image data
img <- readImgData(
    path = file.path(dir, "spatial"),
    sample_id = "sample01")

## as method
(spe <- as(sce, "SpatialExperiment"))
#> class: SpatialExperiment 
#> dim: 50 50 
#> metadata(1): Samples
#> assays(1): counts
#> rownames(50): ENSMUSG00000051951 ENSMUSG00000089699 ...
#>   ENSMUSG00000005886 ENSMUSG00000101476
#> rowData names(3): ID Symbol Type
#> colnames: NULL
#> colData names(3): Sample Barcode sample_id
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> spatialCoords names(0) :
#> imgData names(0):

colData(sce) <- DataFrame(xyz[,c(1:4)])
int_colData(sce)$spatialCoords <- as.matrix(xyz[,c(5,6)])

## Coercing an sce without imgData
(spe <- as(sce, "SpatialExperiment"))
#> class: SpatialExperiment 
#> dim: 50 50 
#> metadata(1): Samples
#> assays(1): counts
#> rownames(50): ENSMUSG00000051951 ENSMUSG00000089699 ...
#>   ENSMUSG00000005886 ENSMUSG00000101476
#> rowData names(3): ID Symbol Type
#> colnames: NULL
#> colData names(5): barcode in_tissue array_row array_col sample_id
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> spatialCoords names(2) : pxl_row_in_fullres pxl_col_in_fullres
#> imgData names(0):

## Coercing an sce with imgData
int_colData(sce)$imgData <- img
(spe <- as(sce, "SpatialExperiment"))
#> class: SpatialExperiment 
#> dim: 50 50 
#> metadata(1): Samples
#> assays(1): counts
#> rownames(50): ENSMUSG00000051951 ENSMUSG00000089699 ...
#>   ENSMUSG00000005886 ENSMUSG00000101476
#> rowData names(3): ID Symbol Type
#> colnames: NULL
#> colData names(5): barcode in_tissue array_row array_col sample_id
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> spatialCoords names(2) : pxl_row_in_fullres pxl_col_in_fullres
#> imgData names(4): sample_id image_id data scaleFactor

## toSpatialExperiment method
colData(sce) <- DataFrame(xyz)
(spe <- toSpatialExperiment(sce,
    imgData = img,
    spatialCoordsNames = c("pxl_col_in_fullres", "pxl_row_in_fullres"),
    sample_id = "sample01"))
#> class: SpatialExperiment 
#> dim: 50 50 
#> metadata(1): Samples
#> assays(1): counts
#> rownames(50): ENSMUSG00000051951 ENSMUSG00000089699 ...
#>   ENSMUSG00000005886 ENSMUSG00000101476
#> rowData names(3): ID Symbol Type
#> colnames: NULL
#> colData names(5): barcode in_tissue array_row array_col sample_id
#> reducedDimNames(0):
#> mainExpName: NULL
#> altExpNames(0):
#> spatialCoords names(2) : pxl_col_in_fullres pxl_row_in_fullres
#> imgData names(4): sample_id image_id data scaleFactor