aggregate-SpatialFeatureExperiment-method: Aggregate data in SFE using geometry

In pachterlab/SpatialFeatureExperiment: Integrating SpatialExperiment with Simple Features in sf

Aggregate data in SFE using geometry

Description

Gene expression and numeric columns of colData will be aggregated with the function specified in FUN, according to another geometry supplied and a geometry predicate (such as st_intersects). For example, when the predicate is st_intersects and a spatial grid is used to aggregate, then the data associated with all cells that intersect with each grid cell will be aggregated with FUN, such as mean or sum. The categorical columns will be collected into list columns, and logical columns will be converted into numeric before applying FUN.

Usage

## S4 method for signature 'SpatialFeatureExperiment'
aggregate(
  x,
  by = NULL,
  FUN = sum,
  sample_id = "all",
  colGeometryName = 1L,
  rowGeometryName = NULL,
  cellsize = NULL,
  square = TRUE,
  flat_topped = FALSE,
  new_geometry_name = "bins",
  join = st_intersects,
  BPPARAM = SerialParam()
)

Arguments

x	An SFE object to be aggregated.
by	A sf data frame whose geometry column is used for aggregation or sfc or for multiple samples a list of sfc whose names are the sample IDs. For multiple samples, the sf data frame must have a column sample_id to indicate which geometry for which sample. This argument is optional if cellsize is specified.
FUN	Function to aggregate the numerical columns in colData and the gene count matrix. This can be sum, mean, or any function that takes a numeric matrix as input and returns a numeric vector whose length is same as the number of rows in the input matrix, such as rowMedians. See package matrixStats. Depending on the function used for aggregation, numeric columns of colData may need to be interpreted differently after aggregation. Aggregation is not done when aggregating by transcript spots in rowGeometry. When it's sum or mean, matrix multiplication is used for aggregation rather than calling the sum or mean function itself; this is much faster than looping through the bins and calling the function on each of them.
sample_id	Which samples to aggregate, defaults to "all".
colGeometryName	Which colGeometry to spatially aggregate the data, by default the first one.
rowGeometryName	Which rowGeometry to spatially aggregate
cellsize	numeric of length 1 or 2 with target cellsize: for square or rectangular cells the width and height, for hexagonal cells the distance between opposite edges (edge length is cellsize/sqrt(3)). A length units object can be passed, or an area unit object with area size of the square or hexagonal cell.
square	logical; if FALSE, create hexagonal grid
flat_topped	logical; if TRUE generate flat topped hexagons, else generate pointy topped
new_geometry_name	Name to give to the new colGeometry in the output. Defaults to "bins".
join	logical spatial predicate function to use if by is a simple features object or geometry; see st_join
BPPARAM	A BiocParallelParam object specifying parallel computing when aggregating data with functions other than sum and mean. Defaults to SerialParam().

Details

For smFISH-based data where the transcript spots are available, the transcript spots can be used instead of cells to aggregate the gene count matrix, in which case all assays other than counts will be dropped and FUN only applies to colData because the transcript spots are simply counted.

What this function does is similar to SEraster but more general because any geometry and more aggregation function can be used, not just regular grids, and the aggregation can be performed on the transcript spots.

Value

An SFE object with colGeometry the same as the geometry specified in by or same as the grid specified in cellsize. rowGeometries and rowData remain the same as in the input x. reducedDims, localResults, colFeatureData (and its colGeometry, annotGeometry, and reducedDim counterparts), and spatialGraphs are dropped because those results no longer apply after aggregation.

Note

For developers: When debugging this function after calling devtools::load_all("."), you may get an error that comes from S3 dispatch of aggregate.Vector from the S4Vectors package. When that happens, either restart the R session, or run setGeneric("aggregate", function(x, ...) standardGeneric("aggregate")) in the console to make an S4 generic as done in the terra package to prioritize S4 dispatch.

Examples

# example code

pachterlab/SpatialFeatureExperiment documentation built on Dec. 20, 2024, 3:41 a.m.