buildSpatialGraph {imcRtools}

R Documentation

Builds an interaction graph based on the cells' locations

Description

Function to define cell-cell interactions via distance-based expansion, delaunay triangulation or k nearest neighbor detection.

Usage

buildSpatialGraph(
  object,
  img_id,
  type = c("expansion", "knn", "delaunay"),
  k = NULL,
  directed = TRUE,
  k_max_dist = NULL,
  threshold = NULL,
  coords = c("Pos_X", "Pos_Y"),
  name = NULL,
  BNPARAM = KmknnParam(),
  BPPARAM = SerialParam(),
  ...
)

Arguments

object	a SingleCellExperiment or SpatialExperiment object
img_id	single character indicating the colData(object) entry containing the unique image identifiers.
type	single character specifying the type of graph to be build. Supported entries are "expansion" (default) to find interacting cells via distance thresholding; "delaunay" to find interactions via delaunay triangulation; "knn" to find the k nearest neighboring cells.
k	(when type = "knn") single numeric integer defining the number of nearest neighbors to search for.
directed	(when type = "knn") should the returned graph be directed? (see details).
k_max_dist	(when type = "knn") the maximum distance at which to consider neighboring cells. All neighbors within a distance larger than k_max_dist will be excluded from graph construction.
threshold	(when type = "expansion") single numeric specifying the maximum distance for considering neighbors
coords	character vector of length 2 specifying the names of the colData (for a SingleCellExperiment object) or the spatialCoords entries of the cells' x and y locations.
name	single character specifying the name of the graph.
BNPARAM	a BiocNeighborParam object defining the algorithm to use.
BPPARAM	a BiocParallelParam-class object defining how to parallelize computations.
...	additional parameters passed to the findNeighbors function (type = "expansion"), the triangulate function (type = "delaunay") or the findKNN function (type = "knn")).

Value

returns a SpatialExperiment or SingleCellExperiment containing the graph in form of a SelfHits object in colPair(object, name).

Building an interaction graph

This function defines interacting cells in different ways. They are based on the cells' centroids and do not incorporate cell shape or area.

1. When type = "expansion", all cells within the radius threshold are considered interacting cells.

2. When type = "delaunay", interacting cells are found via a delaunay triangulation of the cells' centroids.

3. When type = "knn", interacting cells are defined as the k nearest neighbors in the 2D spatial plane.

The directed parameter only affects graph construction via k nearest neighbor search. For directed = FALSE, each interaction will be stored as mutual edge (e.g. node 2 is connected to node 10 and vise versa). For type = "expansion" and type = "delaunay", each edge is stored as mutual edge by default.

The graph is stored in form of a SelfHits object in colPair(object, name). This object can be regarded as an edgelist and coerced to an igraph object via graph_from_edgelist(as.matrix(colPair(object, name))).

Choosing the graph construction method

When finding interactions via expansion or knn, the findNeighbors or findKNN functions are used, respectively. Both functions accept the BNPARAM parameter via which the graph construction method can be defined (default KmknnParam). For an overview on the different algorithms, see BiocNeighborParam. Within the BiocNeighborParam object, distance can be set to "Euclidean" (default), "Manhattan" or "Cosine".

Author(s)

Nils Eling (nils.eling@dqbm.uzh.ch)

See Also

findNeighbors for the function finding interactions via expansion

findKNN for the function finding interactions via nearest neighbor search

triangulate for the function finding interactions via delaunay triangulation

plotSpatial for visualizing spatial graphs

Examples

path <- system.file("extdata/mockData/steinbock", package = "imcRtools")
spe <- read_steinbock(path)

# Constructing a graph via expansion
spe <- buildSpatialGraph(spe, img_id = "sample_id", 
                         type = "expansion", threshold = 10)
colPair(spe, "expansion_interaction_graph")

# Constructing a graph via delaunay triangulation
spe <- buildSpatialGraph(spe, img_id = "sample_id", 
                         type = "delaunay")
colPair(spe, "delaunay_interaction_graph")

# Constructing a graph via k nearest neighbor search
spe <- buildSpatialGraph(spe, img_id = "sample_id", 
                         type = "knn", k = 5)
colPair(spe, "knn_interaction_graph")

---