testInteractions {imcRtools} | R Documentation

## Tests if cell types interact more or less frequently than random

### Description

Cell-cell interactions are summarized in different ways and the resulting count is compared to a distribution of counts arising from random permutations.

### Usage

    testInteractions(
      object,
      group_by,
      label,
      colPairName,
      method = c("classic", "histocat", "patch"),
      patch_size = NULL,
      iter = 1000,
      p_threshold = 0.01,
      BPPARAM = SerialParam()
    )

### Arguments

`object` | a `SingleCellExperiment` or `SpatialExperiment` object.
`group_by` | a single character indicating the `colData(object)` entry by which interactions are grouped. This is usually the image ID or patient ID.
`label` | single character specifying the `colData(object)` entry which stores the cell labels. These can be cell-types labels or other metadata entries.
`colPairName` | single character indicating the `colPair(object)` entry containing cell-cell interactions in form of an edge list.
`method` | which cell-cell interaction counting method to use (see details)
`patch_size` | if `method = "patch"`, a single numeric specifying the minimum number of neighbors of the same type to be considered a patch (see details)
`iter` | single numeric specifying the number of permutations to perform
`p_threshold` | single numeric indicating the empirical p-value threshold at which interactions are considered to be significantly enriched or depleted per group.
`BPPARAM` | parameters for parallelized processing.

### Value

a DataFrame containing one row per `group_by` entry and unique `label` entry combination (`from_label`, `to_label`). The object contains following entries:

- `ct`: stores the interaction count as described in the details

- `p_gt`: stores the fraction of perturbations equal or greater than `ct`

- `p_lt`: stores the fraction of perturbations equal or less than `ct`

- `interaction`: is there the tendency for a positive interaction (attraction) between `from_label` and `to_label`? Is `p_lt` greater than `p_gt`?

- `p`: the smaller value of `p_gt` and `p_lt`.

- `sig`: is `p` smaller than `p_threshold`?

- `sigval`: Combination of `interaction` and `sig`.

  - -1: `interaction == FALSE` and `sig == TRUE`

  - 0: `sig == FALSE`

  - 1: `interaction == TRUE` and `sig == TRUE`

`NA` is returned if a certain label is not present in this grouping level (methods `classic` and `patch`) and if cells with certain labels are not interacting (method `histocat`).

### Counting and summarizing cell-cell interactions

In principle, the `countInteractions` function counts the number of edges (interactions) between each set of unique entries in `colData(object)[[label]]`. Simplified, it counts for each cell of type A the number of neighbors of type B. This count is averaged within each unique entry `colData(object)[[group_by]]` in three different ways:

1. `method = "classic"`: The count is divided by the total number of cells of type A. The final count can be interpreted as "How many neighbors of type B does a cell of type A have on average?"

2. `method = "histocat"`: The count is divided by the number of cells of type A that have at least one neighbor of type B. The final count can be interpreted as "How many many neighbors of type B has a cell of type A on average, given it has at least one neighbor of type B?"

3. `method = "patch"`: For each cell, the count is binarized to 0 (less than `patch_size` neighbors of type B) or 1 (more or equal to `patch_size` neighbors of type B). The binarized counts are averaged across all cells of type A. The final count can be interpreted as "What fraction of cells of type A have at least a given number of neighbors of type B?"

### Testing for significance

Within each unique entry to `colData(object)[[group_by]]`, the entries of `colData(object)[[label]]` are randomized `iter` times. For each iteration, the interactions are counted as described above. The result is a distribution of the interaction count under spatial randomness. The observed interaction count is compared against this Null distribution to derive empirical p-values:

`p_gt`: fraction of perturbations equal or greater than the observed count

`p_lt`: fraction of perturbations equal or less than the observed count

Based on these empirical p-values, the `interaction` score (attraction or avoidance), overall `p` value and significance by comparison to `p_treshold` (`sig` and `sigval`) are derived.

### Author(s)

Vito Zanotelli

Jana Fischer

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

### References

Schulz, D. et al., Simultaneous Multiplexed Imaging of mRNA and Proteins with Subcellular Resolution in Breast Cancer Tissue Samples by Mass Cytometry., Cell Systems 2018 6(1):25-36.e5

Shapiro, D. et al., histoCAT: analysis of cell phenotypes and interactions in multiplex image cytometry data, Nature Methods 2017 14, p. 873–876

### See Also

`countInteractions` for counting (but not testing) cell-cell interactions per grouping level.

`bpparam` for the parallelised backend

### Examples

    library(cytomapper)
    data(pancreasSCE)

    pancreasSCE <- buildSpatialGraph(pancreasSCE, img_id = "ImageNb",
                                     type = "knn", k = 3)

    # Classic style calculation
    (out <- testInteractions(pancreasSCE,
                             group_by = "ImageNb",
                             label = "CellType",
                             method = "classic",
                             colPairName = "knn_interaction_graph",
                             iter = 1000))

    # Histocat style calculation
    (out <- testInteractions(pancreasSCE,
                             group_by = "ImageNb",
                             label = "CellType",
                             method = "histocat",
                             colPairName = "knn_interaction_graph",
                             iter = 1000))

    # Patch style calculation
    (out <- testInteractions(pancreasSCE,
                             group_by = "ImageNb",
                             label = "CellType",
                             method = "patch",
                             patch_size = 3,
                             colPairName = "knn_interaction_graph",
                             ))

[Package imcRtools version 1.0.2 Index]