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")

[Package imcRtools version 1.0.2 Index]