Multivariate spatial data analysis

These functions perform multivariate spatial data analysis, usually spatially informed dimension reduction.

Usage

# S4 method for class 'ANY,SFEMethod'
calculateMultivariate(
  x,
  type,
  listw = NULL,
  transposed = FALSE,
  zero.policy = TRUE,
  p.adjust.method = "BH",
  ...
)

# S4 method for class 'ANY,character'
calculateMultivariate(x, type, listw = NULL, transposed = FALSE, ...)

# S4 method for class 'SpatialFeatureExperiment,ANY'
calculateMultivariate(
  x,
  type,
  colGraphName = 1L,
  subset_row = NULL,
  exprs_values = "logcounts",
  sample_action = c("joint", "separate"),
  BPPARAM = SerialParam(),
  ...
)

runMultivariate(
  x,
  type,
  colGraphName = 1L,
  subset_row = NULL,
  exprs_values = "logcounts",
  sample_action = c("joint", "separate"),
  BPPARAM = SerialParam(),
  name = NULL,
  dest = c("reducedDim", "colData"),
  ...
)

Arguments

x

A numeric matrix whose rows are features/genes, or a SpatialFeatureExperiment (SFE) object with such a matrix in an assay.

type

An SFEMethod object, or a string matching the name of an SFEMethod object. The methods mentioned above correspond to SFEMethod objects already implemented in the Voyager package. Use listSFEMethods to see which methods are available. You can implement new SFEMethod objects to apply Voyager functions to other spatial analysis methods. This is in part inspired by the caret, parsnip, and BiocSingular packages.

listw

Weighted neighborhood graph as a spdep listw object. Not used when the method specified in type does not use a spatial neighborhood graph, such as the variogram.

transposed

Logical, whether the matrix has genes in columns and cells in rows.

zero.policy

default attr(listw, "zero.policy") as set when listw was created, if attribute not set, use global option value; if TRUE assign zero to the lagged value of zones without neighbours, if FALSE assign NA

p.adjust.method

Method to correct for multiple testing, passed to p.adjustSP. Methods allowed are in p.adjust.methods.

...

Extra arguments passed to the specific multivariate method. For example, see multispati_rsp for arguments for MULTISPATI PCA. See localC for arguments for "localC_multi" and "localC_perm_multi".

colGraphName

Name of the listw graph in the SFE object that corresponds to entities represented by columns of the gene count matrix. Use colGraphNames to look up names of the available graphs for cells/spots. Note that for multiple sample_ids, it is assumed that all of them have a graph of this same name.

subset_row

Vector specifying the subset of features to use for dimensionality reduction. This can be a character vector of row names, an integer vector of row indices or a logical vector.

exprs_values

Integer scalar or string indicating which assay of x contains the expression values.

sample_action

Character, either "joint" or "separate". Spatial methods depend on the spatial coordinates and/or spatial neighborhood graph, which is why SpatialExperiment uses sample_id to keep coordinates from different samples separate. Some spatial methods can be sensibly run jointly for multiple samples. In this case, "joint" will run the method jointly for all samples, and "separate" will run the method separately for each sample and concatenate the results.

BPPARAM

A BiocParallelParam object specifying whether and how computing the metric for numerous genes shall be parallelized. This is to parallelize computation across multiple samples when there are a large number of samples. Be cautious if using an optimized BLAS for matrix operations that supports multithreading.

name

Name to use to store the results, defaults to the name in the SFEMethod object passed to argument type. Can be set to distinguish between results from the same method but with different parameters.

dest

Character, either "reducedDim" or "colData". If the output of the multivariate method is a matrix or array, as in spatially informed dimension reduction, then the only option is "reducedDim", so the results will be stored in reducedDim of the SFE object. If the output is a vector, as in the multivariate version of localC, then it will be sotred in colData. Data frame output, such as from localC_perm, can be stored in either reducedDim or colData.

Value

In calculateMultivariate, a matrix for cell embeddings whose attributes include loadings and eigenvalues if relevant, ready to be added to the SFE object with reducedDim setter. For run*, a SpatialFeatureExperiment object with the results added. See Details for where the results are stored.

Details

For the argument type, this package supports "multispati" for MULTISPATI PCA, "localC_multi" for a multivariate generalization of Geary's C, "localC_perm_multi" for the multivariate Geary's C with permutation testing, and "gwpca" for geographically weighted PCA.

References

Dray, S., Said, S. and Debias, F. (2008) Spatial ordination of vegetation data using a generalization of Wartenberg's multivariate spatial correlation. Journal of vegetation science, 19, 45-56.

Anselin, L. (2019), A Local Indicator of Multivariate Spatial Association: Extending Geary's c. Geogr Anal, 51: 133-150. doi:10.1111/gean.12164

Examples

# example code
library(SFEData)
library(scater)
library(scran)
sfe <- McKellarMuscleData()
#> see ?SFEData and browseVignettes('SFEData') for documentation
#> loading from cache
sfe <- logNormCounts(sfe)
gvs <- modelGeneVar(sfe)
hvgs <- getTopHVGs(gvs, fdr.threshold = 0.05)
colGraph(sfe, "visium") <- findVisiumGraph(sfe)
sfe <- runMultivariate(sfe, "multispati", subset_row = hvgs)