Skip to contents

Bivariate spatial statistics

Source: R/bivariate.R
calculateBivariate.Rd

These functions perform bivariate spatial analysis. In this version, the bivariate global method supported are lee, lee.mc, and lee.test from spdep, and cross variograms from gstat (use cross_variogram and cross_variogram_map for type argument, see variogram-internal). Global Lee statistic is computed by my own implementation that is much faster than that in spdep. Bivariate local methods supported are lee (use locallee for type argument) and localmoran_bv a bivariate version of Local Moran in spdep.

Usage

# S4 method for class 'ANY'
calculateBivariate(
  x,
  y = NULL,
  type,
  listw = NULL,
  coords_df = NULL,
  BPPARAM = SerialParam(),
  zero.policy = NULL,
  returnDF = TRUE,
  p.adjust.method = "BH",
  name = NULL,
  ...
)

# S4 method for class 'SpatialFeatureExperiment'
calculateBivariate(
  x,
  type,
  feature1,
  feature2 = NULL,
  colGraphName = 1L,
  colGeometryName = 1L,
  sample_id = "all",
  exprs_values = "logcounts",
  BPPARAM = SerialParam(),
  zero.policy = NULL,
  returnDF = TRUE,
  p.adjust.method = "BH",
  swap_rownames = NULL,
  name = NULL,
  ...
)

runBivariate(
  x,
  type,
  feature1,
  feature2 = NULL,
  colGraphName = 1L,
  colGeometryName = 1L,
  sample_id = "all",
  exprs_values = "logcounts",
  BPPARAM = SerialParam(),
  swap_rownames = NULL,
  zero.policy = NULL,
  p.adjust.method = "BH",
  name = NULL,
  overwrite = FALSE,
  ...
)

Arguments

x

A numeric matrix whose rows are features/genes, or a numeric vector (then y must be specified), or a SpatialFeatureExperiment (SFE) object with such a matrix in an assay.

y

A numeric matrix whose rows are features/genes, or a numeric vector. Bivariate statics will be computed for all pairwise combinations of row names of x and row names of y, except in cross variogram where combinations within x and y are also computed.

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.

coords_df

A sf data frame specifying location of each cell. Not used when the method specified in type uses a spatial neighborhood graph. Must be specified otherwise.

BPPARAM

A BiocParallelParam object specifying whether and how computing the metric for numerous genes shall be parallelized.

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

returnDF

Logical, when the results are not added to a SFE object, whether the results should be formatted as a DataFrame.

p.adjust.method

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

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.

...

Other arguments passed to S4 method (for convenience wrappers like calculateMoransI) or method used to compute metrics as specified by the argument type (as in more general functions like calculateUnivariate). See documentation of functions with the same name as specified in type in the spdep package for the method specific arguments. For variograms, see .variogram.

feature1

ID or symbol of the first genes in SFE object, for the argument x.

feature2

ID or symbol of the second genes in SFE object, for the argument x. Mandatory if length of feature1 is 1.

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.

colGeometryName

Name of a colGeometry sf data frame whose numeric columns of interest are to be used to compute the metric. Use colGeometryNames to look up names of the sf data frames associated with cells/spots. In the SFE method of calculateUnivariate, this is to specify location of cells for methods that don't take a spatial neighborhood graph such as the variogram. If the geometry is not of type POINT, then spatialCoords(x) is used instead.

sample_id

Sample(s) in the SFE object whose cells/spots to use. Can be "all" to compute metric for all samples; the metric is computed separately for each sample.

exprs_values

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

swap_rownames

Column name of rowData(object) to be used to identify features instead of rownames(object) when labeling plot elements. If not found in rowData, then rownames of the gene count matrix will be used.

overwrite

Logical, whether to overwrite existing results with the same name. Defaults to FALSE.

Value

The calculateBivariate function returns a correlation matrix for global Lee, and the results for the each pair of genes for other methods. Global results are not stored in the SFE object. Some methods return one result for each pair of genes, while some return pairwise results for more than 2 genes jointly. Local results are stored in the localResults field in the SFE object, with name the concatenation the two gene names separated by two underscores (__).

Examples

library(SFEData)
library(scater)
library(scran)
library(SpatialFeatureExperiment)
library(SpatialExperiment)
sfe <- McKellarMuscleData()
#> see ?SFEData and browseVignettes('SFEData') for documentation
#> downloading 1 resources
#> retrieving 1 resource
#> loading from cache
sfe <- sfe[,sfe$in_tissue]
sfe <- logNormCounts(sfe)
gs <- modelGeneVar(sfe)
hvgs <- getTopHVGs(gs, fdr.threshold = 0.01)
g <- colGraph(sfe, "visium") <- findVisiumGraph(sfe)

# Matrix method
mat <- logcounts(sfe)[hvgs[1:5],]
df <- df2sf(spatialCoords(sfe), spatialCoordsNames(sfe))
out <- calculateBivariate(mat, type = "lee", listw = g)
#> Warning: `listw2sparse()` was deprecated in SpatialFeatureExperiment 1.9.0.
#> ℹ Please use `spatialreg::as_dgRMatrix_listw()` instead.
#> ℹ The deprecated feature was likely used in the Voyager package.
#>   Please report the issue at <https://github.com/pachterlab/voyager/issues>.
out <- calculateBivariate(mat, type = "cross_variogram", coords_df = df)

# SFE method
out <- calculateBivariate(sfe, type = "lee",
feature1 = c("Myh1", "Myh2", "Csrp3"), swap_rownames = "symbol")
out2 <- calculateBivariate(sfe, type = "lee.test", feature1 = "Myh1",
feature2 = "Myh2", swap_rownames = "symbol")
sfe <- runBivariate(sfe, type = "locallee", feature1 = "Myh1",
feature2 = "Myh2", swap_rownames = "symbol")