% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/testInteractions.R
\name{testInteractions}
\alias{testInteractions}
\title{Tests if cell types interact more or less frequently than random}
\usage{
testInteractions(
  object,
  group_by,
  label,
  colPairName,
  method = c("classic", "conditional", "patch", "interaction"),
  patch_size = NULL,
  iter = 1000,
  p_threshold = 0.01,
  return_samples = FALSE,
  tolerance = sqrt(.Machine$double.eps),
  BPPARAM = SerialParam()
)
}
\arguments{
\item{object}{a \code{SingleCellExperiment} or \code{SpatialExperiment}
object.}

\item{group_by}{a single character indicating the \code{colData(object)}
entry by which interactions are grouped. This is usually the image ID or
patient ID.}

\item{label}{single character specifying the \code{colData(object)} entry
which stores the cell labels. These can be cell-types labels or other
metadata entries.}

\item{colPairName}{single character indicating the \code{colPair(object)}
entry containing cell-cell interactions in form of an edge list.}

\item{method}{which cell-cell interaction counting method to use 
(see details)}

\item{patch_size}{if \code{method = "patch"}, a single numeric specifying
the minimum number of neighbors of the same type to be considered a patch
(see details)}

\item{iter}{single numeric specifying the number of permutations to perform}

\item{p_threshold}{single numeric indicating the empirical p-value 
threshold at which interactions are considered to be significantly 
enriched or depleted per group.}

\item{return_samples}{single logical indicating if the permuted interaction
counts of all iterations should be returned.}

\item{tolerance}{single numeric larger than 0. This parameter defines the
difference between the permuted count and the actual counts at which both
are regarded as equal. Default taken from \code{all.equal}.}

\item{BPPARAM}{parameters for parallelized processing.}
}
\value{

}
\description{
Cell-cell interactions are summarized in different ways and
the resulting count is compared to a distribution of counts arising 
from random permutations.
}
\section{Counting and summarizing cell-cell interactions}{

In principle, the \code{\link{countInteractions}} function counts the number
of edges (interactions) between each set of unique entries in 
\code{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 
\code{colData(object)[[group_by]]} in four different ways:

1. \code{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. \code{method = "conditional"}: Formerly named "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 neighbors of type B has a cell of 
type A on average, given it has at least one neighbor of type B?".

3. \code{method = "patch"}: For each cell, the count is binarized to 0 
(less than \code{patch_size} neighbors of type B) or 1 (more or equal to 
\code{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?"

4. \code{method = "interaction"}: The count is divided by the total number of 
interactions from cell type A. The final count can be interpreted as "What 
fraction of interactions of cell type A occur with cell type B."
}

\section{Testing for significance}{
 Within each unique entry to
\code{colData(object)[[group_by]]}, the entries of
\code{colData(object)[[label]]} are randomized \code{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:

\code{p_gt}: fraction of perturbations equal or greater than the observed 
count

\code{p_lt}: fraction of perturbations equal or less than the observed count

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

\examples{
library(cytomapper)
library(BiocParallel)
data(pancreasSCE)

pancreasSCE <- buildSpatialGraph(pancreasSCE, img_id = "ImageNb", 
                                 type = "knn", k = 3)
                               
# Classic style calculation - setting the seed inside SerialParam for reproducibility
(out <- testInteractions(pancreasSCE, 
                         group_by = "ImageNb",
                         label = "CellType", 
                         method = "classic",
                         colPairName = "knn_interaction_graph",
                         iter = 1000,
                         BPPARAM = SerialParam(RNGseed = 123)))
                                
# Conditional style calculation
(out <- testInteractions(pancreasSCE, 
                         group_by = "ImageNb",
                         label = "CellType", 
                         method = "conditional",
                         colPairName = "knn_interaction_graph",
                         iter = 1000,
                         BPPARAM = SerialParam(RNGseed = 123)))
                                
# Patch style calculation
(out <- testInteractions(pancreasSCE, 
                         group_by = "ImageNb",
                         label = "CellType", 
                         method = "patch",
                         patch_size = 3,
                         colPairName = "knn_interaction_graph",
                         iter = 1000,
                         BPPARAM = SerialParam(RNGseed = 123)))
                         
# Interaction style calculation
(out <- testInteractions(pancreasSCE, 
                         group_by = "ImageNb",
                         label = "CellType", 
                         method = "interaction",
                         colPairName = "knn_interaction_graph"))

}
\references{
\href{https://www.sciencedirect.com/science/article/pii/S2405471217305434}{
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}

\href{https://www.nature.com/articles/nmeth.4391}{
Schapiro, D. et al., histoCAT: analysis of cell phenotypes and interactions in 
multiplex image cytometry data, Nature Methods 2017 14, p. 873–876}

\href{https://doi.org/10.1101/2025.03.31.646289}{
Schiller, C. et al., Comparison and Optimization of Cellular Neighbor Preference Methods 
for Quantitative Tissue Analysis, biorRxiv 2025.03.31.646289}
}
\seealso{
\code{\link{countInteractions}} for counting (but not testing) cell-cell
interactions per grouping level.
  
\code{\link[BiocParallel]{bpparam}} for the parallelised backend
}
\author{
Vito Zanotelli

Jana Fischer

adapted by Nils Eling (\email{nils.eling@dqbm.uzh.ch})

adapted by Marlene Lutz (\email{marlene.lutz@uzh.ch})

adapted by Chiara Schiller (\email{chiara.schiller@uni-heidelberg.de})
}
