rasterizeMatrix

Function to rasterize a given input matrix (both dense or sparse) based on a given position matrix.

This function assumes that inputs are provided as a dgCmatrix or matrix for data and matrix for position.

Usage

rasterizeMatrix(
  data,
  pos,
  bbox,
  resolution = 100,
  square = TRUE,
  fun = "mean",
  n_threads = 1,
  BPPARAM = NULL,
  verbose = TRUE
)

Arguments

data

dgCmatrix or matrix: Feature x observation matrix represented as a dgCmatrix or matrix object. Features can be genes or cell types. In the case of features being cell types, this matrix is assumed to be a sparse model matrix with rows as cell types and columns as cell IDs.

pos

matrix: Spatial x,y coordinates of observations stored as a matrix array. Further, x,y coordinates are assumed to be stored in column 1 and 2 of spatialCoords.

bbox

bbox or numeric: Bounding box for rasterization defined by a bbox class object (as created by sf::st_bbox) or a numeric vector of length four, with xmin, ymin, xmax and ymax values. Values in a numeric vector are assumed to be in the order of xmin, ymin, xmax, and ymax.

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 the average of gene expression for all cells within the pixel. If "sum", pixel value for each pixel would be the 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

The output is returned as a list containing rasterized feature x observation matrix as dgCmatrix if data was given as dgCmatrix and as matrix if data was given as matrix, spatial x,y coordinates of pixel centroids as matrix, and data.frame 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).

Examples

library(SpatialExperiment)
library(sf)

data("merfish_mousePOA")
# extract features-by-cells matrix, spatial coordinates from the SpatialExperiment object
data <- assay(merfish_mousePOA)
pos <- spatialCoords(merfish_mousePOA)
# compute bounding box
resolution <- 100
bbox <- st_bbox(c(
  xmin = floor(min(pos[,1])-resolution/2), 
  xmax = ceiling(max(pos[,1])+resolution/2), 
  ymin = floor(min(pos[,2])-resolution/2), 
  ymax = ceiling(max(pos[,2])+resolution/2)
))
# rasterize with mean as the aggregation function
out_mean <- rasterizeMatrix(data, pos, bbox, resolution = resolution, fun = "mean")
# rasterize with sum as the aggregation function
out_sum <- rasterizeMatrix(data, pos, bbox, resolution = resolution, fun = "sum")
# rasterize with user-defined resolution and hexagonal pixels
# in this case, you need to update the bbox as well
resolution <- 200
bbox <- st_bbox(c(
  xmin = floor(min(pos[,1])-resolution/2), 
  xmax = ceiling(max(pos[,1])+resolution/2), 
  ymin = floor(min(pos[,2])-resolution/2), 
  ymax = ceiling(max(pos[,2])+resolution/2)
))
out_hex <- rasterizeMatrix(data, pos, bbox, resolution = resolution, square = FALSE, fun = "mean")