rasterizeGeneExpression

Function to rasterize feature x observation matrix in spatially-resolved omics data represented as SpatialExperiment class.

This function assumes that the input is provided as a SpatialExperiment object or a list of SpatialExperiment objects.

Usage

rasterizeGeneExpression(
  input,
  assay_name = NULL,
  resolution = 100,
  square = TRUE,
  fun = "mean",
  n_threads = 1,
  BPPARAM = NULL,
  verbose = FALSE
)

Arguments

input

SpatialExperiment or list: Input data represented as a SpatialExperiment or list of SpatialExperiment. Each SpatialExperiment is assumed to have an assay slot containing feature (genes) x observation (cells) matrix as dgCmatrix or matrix and a spatialCoords slot containing spatial x,y coordinates of observations as matrix array. Further, x,y coordinates are assumed to be stored in column 1 and 2 of spatialCoords.

assay_name

character: Name of the assay slot of the input that you want to apply rasterization. If no argument is given, the first assay of the input would be rasterized. This argument is useful when you have both raw and normalized assays stored in the input, and you want to apply rasterization to the normalized assay. If the input is a list, assay_name is assumed to be present in all elements (SpatialExperiment) of the input.

resolution

integer or double: Resolution refers to the side length of each pixel for square pixels and the distance between opposite edges of each pixel for hexagonal pixels. The unit of this parameter is assumed to be the same as the unit of spatial coordinates of the input data.

square

logical: If TRUE (default), rasterize into square pixels. If FALSE, rasterize into hexagonal pixels.

fun

character: If "mean", pixel value for each pixel would be mean of gene expression for all cells within the pixel. If "sum", pixel value for each pixel would be sum of gene expression for all cells within the pixel.

n_threads

integer: Number of threads for parallelization. Default = 1. Inputting this argument when the BPPARAM argument is missing would set parallel exeuction back-end to be BiocParallel::MulticoreParam(workers = n_threads). We recommend setting this argument to be the number of cores available (parallel::detectCores(logical = FALSE)). If BPPARAM argument is not missing, the BPPARAM argument would override n_threads argument.

BPPARAM

BiocParallelParam: Optional additional argument for parallelization. This argument is provided for advanced users of BiocParallel for further flexibility for setting up parallel-execution back-end. Default is NULL. If provided, this is assumed to be an instance of BiocParallelParam.

verbose

logical: Whether to display verbose output or warning. Default is FALSE

Value

If the input was given as SpatialExperiment, the output is returned as a new SpatialExperiment object with assay slot containing the feature (genes) x observations (pixels) matrix (dgCMatrix or matrix depending on the input, see documentation for rasterizeMatrix), spatialCoords slot containing spatial x,y coordinates of pixel centroids, and colData slot containing meta data for pixels (number of cells that were aggregated in each pixel, cell IDs of cells that were aggregated in each pixel, pixel type based on the square argument, pixel resolution based on the resolution argument, pixel geometry as sfc_POLYGON). If the input was provided as list of SpatialExperiment, the output is returned as a new list of SpatialExperiment containing information described above for corresponding SpatialExperiment. Further, names(input) is inherited in the output.

Examples

library(SpatialExperiment)

data("merfish_mousePOA")

# check assay names for this particular SpatialExperiment object (should be "volnorm")
assayNames(merfish_mousePOA)
#> [1] "volnorm"

# rasterize a single SpatialExperiment object
# make sure to specify the assay_name argument when the input SpatialExperiment 
# object has multiple assay names (assay_name is used here as an example)
out <- rasterizeGeneExpression(merfish_mousePOA, assay_name = "volnorm", fun = "mean")

# rasterize a single SpatialExperiment object with user-defined resolution and hexagonal pixels
out <- rasterizeGeneExpression(merfish_mousePOA, assay_name = "volnorm", resolution = 200, 
square = FALSE, fun = "mean")

# rasterize a list of SpatialExperiment objects (in this case, permutated datasets 
# with 3 different rotations)
spe_list <- permutateByRotation(merfish_mousePOA, n_perm = 3)
out_list <- rasterizeGeneExpression(spe_list, assay_name = "volnorm", resolution = 100, 
square = TRUE, fun = "mean")