1 Class structure

The SpatialExperiment class is designed to represent spatially resolved transcriptomics (ST) data. It inherits from the SingleCellExperiment class and is used in the same manner. In addition, the class supports storage of spatial information via spatialData and spatialCoords, and storage of images via imgData.

For demonstration of the general class structure, we load an example SpatialExperiment (abbreviated as SPE) object (variable spe):

library(SpatialExperiment)
## Loading required package: SingleCellExperiment
## Loading required package: SummarizedExperiment
## Loading required package: MatrixGenerics
## Loading required package: matrixStats
## 
## Attaching package: 'MatrixGenerics'
## The following objects are masked from 'package:matrixStats':
## 
##     colAlls, colAnyNAs, colAnys, colAvgsPerRowSet, colCollapse,
##     colCounts, colCummaxs, colCummins, colCumprods, colCumsums,
##     colDiffs, colIQRDiffs, colIQRs, colLogSumExps, colMadDiffs,
##     colMads, colMaxs, colMeans2, colMedians, colMins, colOrderStats,
##     colProds, colQuantiles, colRanges, colRanks, colSdDiffs, colSds,
##     colSums2, colTabulates, colVarDiffs, colVars, colWeightedMads,
##     colWeightedMeans, colWeightedMedians, colWeightedSds,
##     colWeightedVars, rowAlls, rowAnyNAs, rowAnys, rowAvgsPerColSet,
##     rowCollapse, rowCounts, rowCummaxs, rowCummins, rowCumprods,
##     rowCumsums, rowDiffs, rowIQRDiffs, rowIQRs, rowLogSumExps,
##     rowMadDiffs, rowMads, rowMaxs, rowMeans2, rowMedians, rowMins,
##     rowOrderStats, rowProds, rowQuantiles, rowRanges, rowRanks,
##     rowSdDiffs, rowSds, rowSums2, rowTabulates, rowVarDiffs, rowVars,
##     rowWeightedMads, rowWeightedMeans, rowWeightedMedians,
##     rowWeightedSds, rowWeightedVars
## Loading required package: GenomicRanges
## Loading required package: stats4
## Loading required package: BiocGenerics
## 
## Attaching package: 'BiocGenerics'
## The following objects are masked from 'package:stats':
## 
##     IQR, mad, sd, var, xtabs
## The following objects are masked from 'package:base':
## 
##     Filter, Find, Map, Position, Reduce, anyDuplicated, append,
##     as.data.frame, basename, cbind, colnames, dirname, do.call,
##     duplicated, eval, evalq, get, grep, grepl, intersect, is.unsorted,
##     lapply, mapply, match, mget, order, paste, pmax, pmax.int, pmin,
##     pmin.int, rank, rbind, rownames, sapply, setdiff, sort, table,
##     tapply, union, unique, unsplit, which.max, which.min
## Loading required package: S4Vectors
## 
## Attaching package: 'S4Vectors'
## The following objects are masked from 'package:base':
## 
##     I, expand.grid, unname
## Loading required package: IRanges
## Loading required package: GenomeInfoDb
## Loading required package: Biobase
## Welcome to Bioconductor
## 
##     Vignettes contain introductory material; view with
##     'browseVignettes()'. To cite Bioconductor, see
##     'citation("Biobase")', and for packages 'citation("pkgname")'.
## 
## Attaching package: 'Biobase'
## The following object is masked from 'package:MatrixGenerics':
## 
##     rowMedians
## The following objects are masked from 'package:matrixStats':
## 
##     anyMissing, rowMedians
example(read10xVisium, echo = FALSE)
spe
## class: SpatialExperiment 
## dim: 50 99 
## metadata(0):
## assays(1): counts
## rownames(50): ENSMUSG00000051951 ENSMUSG00000089699 ...
##   ENSMUSG00000005886 ENSMUSG00000101476
## rowData names(1): symbol
## colnames(99): AAACAACGAATAGTTC-1 AAACAAGTATCTCCCA-1 ...
##   AAAGTCGACCCTCAGT-1 AAAGTGCCATCAATTA-1
## colData names(1): sample_id
## reducedDimNames(0):
## mainExpName: NULL
## altExpNames(0):
## spatialData names(3) : in_tissue array_row array_col
## spatialCoords names(2) : pxl_col_in_fullres pxl_row_in_fullres
## imgData names(4): sample_id image_id data scaleFactor

1.1 spatialData & -Coords

In addition to observation metadata stored inside the colData slot of a SingleCellExperiment, the SpatialExperiment class can accommodate:

  • spatialData, a DataFrame containing spatial metadata
    (e.g. whether or not an observation was mapped to tissue)
  • spatialCoords, a numeric matrix of spatial coordinates (e.g. x and y)

Both spatialData and spatialCoords are stored separately inside the int_colData slot.

Note that the colData, spatialData, and spatialCoords slots follow a hierarchical structure where colData > spatialData > spatialCoords. Here, each accessor function allows joint accession of the target slot, and (optionally) any slot(s) that precedes it.

Specifically, the following commands are supported that may be used to access specific subsets of (spatial) metadata associated with each column (observation, e.g. spots or cells) in a SPE:

spatialCoords(spe)

spatialData(spe)
spatialData(spe, spatialCoords = TRUE)

colData(spe, spatialData = TRUE)
colData(spe, spatialCoords = TRUE)
colData(spe, spatialData = TRUE, spatialCoords = TRUE)

1.2 imgData

All image related data are stored inside the int_metadata’s imgData field as a DataFrame of the following structure:

  • each row corresponds to one image for a given sample
    and with a given unique image identifier (e.g. its resolutions)
  • for each image, columns specify:
    • which sample_id the image belongs to
    • a unique image_id in order to accommodate multiple images
      for a given sample (e.g. of different resolutions)
    • the image’s data (a SpatialImage object)
    • the scaleFactor that adjusts pixel positions of the original,
      full-resolution image to pixel positions in the image

The imgData() accessor can be used to retrieve the image data stored within the object:

imgData(spe)
## DataFrame with 2 rows and 4 columns
##     sample_id    image_id   data scaleFactor
##   <character> <character> <list>   <numeric>
## 1    section1      lowres   ####   0.0510334
## 2    section2      lowres   ####   0.0510334

1.2.1 The SpatialImage class

Images are stored inside the data field of the imgData as a list of SpatialImages. Each image may be of one of the following sub-classes:

  • LoadedSpatialImage
    • represents an image that is fully realized into memory as a raster object
    • @image contains a raster object: a matrix of RGB colors for each pixel in the image
  • StoredSpatialImage
    • represents an image that is stored in a local file (e.g., as
      .png, .jpg or .tif), and loaded into memory only on request
    • @path specifies a local file from which to retrieve the image
  • RemoteSpatialImage
    • represents an image that is remotely hosted
      (under some URL), and retrieved only on request
    • @url specifies where to retrieve the image from

A SpatialImage can be accessed using getImg(), or retrieved directly from the imgData():

(spi <- getImg(spe))
## A 600 x 576 StoredSpatialImage 
## imgSource(): 
##   /tmp/RtmpGjXjlV/Rinst21541f790c1ff1/Spat
##   ialExperiment/extdata/10xVisium/section1
##   /spatial/tissue_lowres_image.png
identical(spi, imgData(spe)$data[[1]])
## [1] TRUE

Data available in an object of class SpatialImage may be accessed via the imgRaster() and imgSource() accessors:

plot(imgRaster(spe))