SFEMethod class

This S4 class is used to wrap spatial analysis methods, taking inspiration from the caret and tidymodels packages.

Usage

SFEMethod(
  name,
  fun,
  reorganize_fun,
  package,
  variate = c("uni", "bi", "multi"),
  scope = c("global", "local"),
  title = NULL,
  default_attr = NA,
  args_not_check = NA,
  joint = FALSE,
  use_graph = TRUE,
  use_matrix = FALSE,
  dest = c("reducedDim", "colData")
)

# S4 method for SFEMethod
info(x, type)

# S4 method for SFEMethod
is_local(x)

# S4 method for SFEMethod
fun(x)

# S4 method for SFEMethod
reorganize_fun(x)

# S4 method for SFEMethod
args_not_check(x)

# S4 method for SFEMethod
is_joint(x)

# S4 method for SFEMethod
use_graph(x)

# S4 method for SFEMethod
use_matrix(x)

Arguments

name

Name of the method, used by user-facing functions to specify the method to use, such as "moran" for Moran's I.

fun

Function to run the method. See Details.

reorganize_fun

Function to reorganize results to add to the SFE object. See Details.

package

Name of the package whose implementation of the method is used here, used to check if the package is installed.

variate

How many variables this method works with, must be one of "uni" for univariate, "bi" for bivariate, or "multi" for multivariate.

scope

Either "global", returning one result for the entire dataset, or "local", returning one result for each spatial location. For multivariate methods, this is irrelevant.

title

Descriptive title to show when plotting the results.

default_attr

For local methods that return multiple fields, such as local Moran values and their p-values, the default field to use when plotting.

args_not_check

A character vector indicating which argument are not to be checked when comparing parameters in with those of a previous run.

joint

Logical, whether it makes sense to run this method to multiple samples jointly. If TRUE, then fun must be able to handle an adjacency matrix for the listw argument because there's no straightforward way to concatenate listw objects from multiple samples.

use_graph

Logical, to indicate whether the method uses a spatial neighborhood graph because unifying the user facing functions have an argument asking for the graph as most though not all methods require the graph.

use_matrix

Logical, whether the function in slot fun takes a matrix as input. The argument is only used for bivariate methods.

dest

Whether the results are more appropriate for reducedDim or colData. Only used for multivariate methods. This overrides the "local" field in info.

x

A SFEMethod object

type

One of the names of the info slot, see slot documentation.

Value

The constructor returns a SFEMethod object. The getters return the content of the corresponding slots.

Details

The fun slot should be specified as such:

For all methods, there must be arguments x for a vector, listw for a listw object specifying the spatial neighborhood graph, zero.policy specifying what to do with cells without neighbors (default NULL, use global option value; if TRUE assign zero to the lagged value of zones without neighbours, if FALSE assign NA), and optionally other method specific arguments and ... to pass to the underlying imported function. If the original function implementing the method in the package has different argument names or orders, write a thin wrapper to rearrange and/or rename the arguments.

For univariate methods that use a spatial neighborhood graph, the first two arguments must be x and listw. For univariate methods that don't use a spatial neighborhood graph, such as the variogram, the first two arguments must be x for a numeric vector and coords_df for a sf data frame with cell locations and optionally other regressors. The formula argument is optional and can have defaults specifying regressors to use.

For bivariate methods, the first three arguments must be x, y, and listw.

For multivariate methods, the argument x is mandatory, for the matrix input. These arguments must be present but can be optional by having defaults: listw and ncomponents to set the number of dimentions in the output.

The reorganize_fun slot should be specified as such:

Univariate methods are meant to be run separately for each gene, so the input to reorganize_fun in the argument out should be a list of outputs; each element of the list corresponds to the output of a gene.

For univariate global methods, different fields of the result should be columns of a data frame with one row so results for multiple features will be a data frame. The arguments should be out, and name to rename the primary field if a more informative name is needed, and ... for other arguments specific to methods. The output of reorganize_fun should be a DataFrame whose rows correspond to the genes and columns correspond to fields in the output.

For univariate local methods, the arguments should be out, nb for a neighborhood list used for multiple testing correction, and p.adjust.method for a method to correct for multiple testing as in p.adjust, and .... The output of reorganize_fun should be a list of reorganized output. Each element of the list corresponds to a gene, and the reorganized content of the element can be a vector, matrix, or data frame, but they must all have the same dimensions for all genes. Each element of the vector, or each row of the matrix or data frame corresponds to a cell.

For multivariate methods whose results go into reducedDim, reorganize_fun should have one argument out for the raw output. The output of reorganize_fun should be the cell embedding matrix ready to be added to reducedDim. Other relevant information such as gene loadings and eigenvalues should be added to the attributes of the cell embedding matrix.

For multivariate methods whose results can go into colData, the arguments should be out, nb, and p.adjust.method. Unlike the univariate local counterpart, out takes the raw output instead of a list of outputs. The output of reorganize_fun is a vector or a data frame ready to be added to colData.

Slots

info

A named character vector specifying information about the method.

fun

The function implementing the method. See Details.

reorganize_fun

Function to convert output from fun into a format to store in the SFE object. See Details.

misc

Miscellaneous information on how the method interacts with the rest of the package. This should be a named list.

Examples

moran <- SFEMethod(
name = "moran", title = "Moran's I", package = "spdep", variate = "uni",
scope = "global",
fun = function(x, listw, zero.policy = NULL)
    spdep::moran(x, listw, n = length(listw$neighbours), S0 = spdep::Szero(listw),
                 zero.policy = zero.policy),
reorganize_fun = Voyager:::.moran2df
)