R/buildSpatialGraph.R
buildSpatialGraph.RdFunction to define cell-cell interactions via distance-based expansion, delaunay triangulation or k nearest neighbor detection.
a SingleCellExperiment or SpatialExperiment
object
single character indicating the colData(object) entry
containing the unique image identifiers.
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.
(when type = "knn") single numeric integer defining the
number of nearest neighbors to search for.
(when type = "knn") should the returned graph be
directed? (see details).
(when type = "knn" or type = "delaunay") the
maximum distance at which to consider neighboring cells. All neighbors
within a distance larger than max_dist will be excluded from graph
construction.
(when type = "expansion") single numeric specifying
the maximum distance for considering neighbors
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.
single character specifying the name of the graph.
a BiocNeighborParam object
defining the algorithm to use.
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")).
returns a SpatialExperiment or SingleCellExperiment
containing the graph in form of a SelfHits object in
colPair(object, name). The object is grouped by entries in the
img_id slot.
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))).
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".
The buildSpatialGraph function operates on individual images.
Therefore the returned object is grouped by entries in img_id.
This means all cells of a given image are grouped together in the object.
The ordering of cells within each individual image is the same as the ordering
of these cells in the input object.
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
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)
#> The returned object is ordered by the 'sample_id' entry.
colPair(spe, "expansion_interaction_graph")
#> SelfHits object with 1242 hits and 0 metadata columns:
#> from to
#> <integer> <integer>
#> [1] 1 3
#> [2] 3 1
#> [3] 3 5
#> [4] 3 6
#> [5] 3 7
#> ... ... ...
#> [1238] 403 404
#> [1239] 404 398
#> [1240] 404 399
#> [1241] 404 402
#> [1242] 404 403
#> -------
#> nnode: 404
# Constructing a graph via delaunay triangulation
spe <- buildSpatialGraph(spe, img_id = "sample_id",
type = "delaunay")
#> The returned object is ordered by the 'sample_id' entry.
colPair(spe, "delaunay_interaction_graph")
#> SelfHits object with 2046 hits and 0 metadata columns:
#> from to
#> <integer> <integer>
#> [1] 1 2
#> [2] 1 3
#> [3] 1 4
#> [4] 1 5
#> [5] 1 10
#> ... ... ...
#> [2042] 403 404
#> [2043] 404 398
#> [2044] 404 399
#> [2045] 404 402
#> [2046] 404 403
#> -------
#> nnode: 404
# Constructing a graph via k nearest neighbor search
spe <- buildSpatialGraph(spe, img_id = "sample_id",
type = "knn", k = 5)
#> The returned object is ordered by the 'sample_id' entry.
colPair(spe, "knn_interaction_graph")
#> SelfHits object with 2020 hits and 0 metadata columns:
#> from to
#> <integer> <integer>
#> [1] 1 3
#> [2] 1 4
#> [3] 1 5
#> [4] 1 6
#> [5] 1 7
#> ... ... ...
#> [2016] 404 398
#> [2017] 404 399
#> [2018] 404 401
#> [2019] 404 402
#> [2020] 404 403
#> -------
#> nnode: 404